uiv: Bootstrap 3 Components for Vue 3

Common errors

• Failed to resolve component: uiv-modal

  cause The uiv library or a specific component was not correctly registered with the Vue application.
  fix Ensure you have `app.use(uiv)` in your main application entry point (e.g., `main.js`) if you are using global registration. Alternatively, if importing individual components, make sure they are properly imported and registered locally or globally.

• TypeError: Cannot read properties of undefined (reading 'use')

  cause `app` is not a valid Vue 3 application instance, or you are trying to use `app.use()` on a Vue 2 instance or a non-Vue object.
  fix Confirm you are creating your Vue application with `createApp()` (Vue 3) and that `app` refers to the return value of this function, e.g., `const app = createApp(App)`.

• Uncaught TypeError: $(...).tooltip is not a function

  cause This error typically indicates that jQuery and Bootstrap's JavaScript (which depends on jQuery for its components like tooltips) are not loaded or initialized, but uiv does not depend on them. If you see this error, it's likely from *another* Bootstrap-related library or custom script, not uiv itself. uiv is jQuery-free.
  fix This error is generally NOT related to `uiv`. If you encounter it, check if you have other Bootstrap-related JavaScript libraries or custom scripts that mistakenly expect jQuery and Bootstrap's JS. uiv components are implemented natively in Vue.

Warnings

• breaking uiv v2.0.0 and above are exclusively for Vue 3. Projects using Vue 2 must remain on uiv v1.x (or v0.x). The API might have minor changes due to Vue 3's composition API and other breaking changes.
  Fix: For Vue 3 projects, install `uiv@^2`. For Vue 2 projects, install `uiv@^1`. Review the migration guide if upgrading an existing Vue 2 project to Vue 3 and uiv v2.
• gotcha uiv components require Bootstrap 3's CSS for proper styling. The library does not bundle this CSS. Failing to import `bootstrap/dist/css/bootstrap.min.css` (or a custom Bootstrap build) will result in unstyled components.
  Fix: Ensure `import 'bootstrap/dist/css/bootstrap.min.css'` is present in your main application entry file (e.g., `main.js` or `App.vue` script setup).
• gotcha The `Btn` component in uiv v2.0.6 (and potentially earlier v2 versions) internally uses `RouterLink` from `vue-router`. If `vue-router` is not installed and configured in your Vue 3 application, using the `Btn` component may lead to errors or unexpected behavior, especially when attempting to use its routing capabilities.
  Fix: If using the `Btn` component with routing functionality, ensure `vue-router` is installed and registered with your Vue application (e.g., `app.use(router)`). If you only need a simple button, consider using a standard HTML `<button>` or another uiv component without routing properties.
• gotcha Directives like `v-uiv-tooltip` or `v-uiv-popover` are provided. Remember to register uiv as a plugin (`app.use(uiv)`) for these directives to be globally available. If only specific components are imported, directives will not be automatically registered.
  Fix: Always call `app.use(uiv)` if you intend to use any of the provided directives. If you need to use directives without global registration, you may need to import and register them locally (refer to uiv documentation for specific directive imports).

Install

• npm install uiv npm
• yarn add uiv yarn
• pnpm add uiv pnpm

Imports

• * as uiv
  wrong:

  const uiv = require('uiv')

  correct:

  import * as uiv from 'uiv'

  For global registration as a Vue plugin via `app.use(uiv)`. Prior to v2, CommonJS `require` was more common. In Vue 3, ESM is standard.
• Specific Component (e.g., Modal)
  wrong:

  import Modal from 'uiv/components/modal'

  correct:

  import { Modal } from 'uiv'

  Recommended for tree-shaking and only importing necessary components. The direct path import (`uiv/components/modal`) was a common pattern in older versions or other libraries but is not standard for uiv v2.
• Bootstrap CSS
  wrong:

  import 'uiv/dist/uiv.min.css'

  correct:

  import 'bootstrap/dist/css/bootstrap.min.css'

  uiv does NOT ship with its own CSS. You MUST include Bootstrap's CSS separately in your project for proper styling. This is a frequent oversight.
• Types (for TypeScript)

  import type { DropdownOption } from 'uiv'

  uiv ships with TypeScript definitions, allowing for type-safe usage of its components and utility types.

Quickstart

This quickstart demonstrates how to initialize uiv as a Vue 3 plugin and use a basic modal component, highlighting the necessity of importing Bootstrap's CSS.

import 'bootstrap/dist/css/bootstrap.min.css'
import { createApp, h } from 'vue'
import * as uiv from 'uiv'

const App = {
  template: `
    <div class="container">
      <h1>uiv Example</h1>
      <button type="button" class="btn btn-primary" @click="showModal = true">
        Open Modal
      </button>
      <uiv-modal v-model="showModal" title="Hello uiv!" @hide="onModalHide">
        This is a simple modal dialog using uiv components. Ensure Bootstrap CSS is imported!
        <template #footer>
          <button type="button" class="btn btn-default" @click="showModal = false">Close</button>
          <button type="button" class="btn btn-primary" @click="showAlert">Do Something</button>
        </template>
      </uiv-modal>
    </div>
  `,
  data() {
    return {
      showModal: false
    }
  },
  methods: {
    onModalHide() {
      console.log('Modal was hidden')
    },
    showAlert() {
      alert('Action taken!')
      this.showModal = false
    }
  }
}

const app = createApp(App)
app.use(uiv)
app.mount('#app')