Installation - Bitrix24 UI for Vue

Setup

Use our Vue starter

Start your project using the bitrix24/starter-b24ui-vue template with Bitrix24 UI pre-configured.

Create a new project locally by running the following command:

git clone https://github.com/bitrix24/starter-b24ui-vue.git <project-name>
cd <project-name>
pnpm install
pnpm run dev

The <project-name> argument is the name of the directory where the project will be created, replace it with your project name.

Add to a Vue project

Install the Bitrix24 UI package

pnpm add @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

yarn add @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

npm install @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

bun add @bitrix24/b24ui-nuxt @bitrix24/b24icons-vue tailwindcss

Add the Bitrix24 UI Vite plugin in your `vite.config.ts`

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite()
  ]
})

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'
import laravel from 'laravel-vite-plugin'

export default defineConfig({
  plugins: [
    laravel({
      input: ['resources/js/app.ts'],
      refresh: true
    }),
    vue({
      template: {
        transformAssetUrls: {
          base: null,
          includeAbsolute: false
        }
      }
    }),
    bitrix24UIPluginVite({
      router: 'inertia'
    })
  ]
})

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'
import adonisjs from '@adonisjs/vite/client'
import inertia from '@adonisjs/inertia/client'

export default defineConfig({
  plugins: [
    adonisjs({
      entrypoints: ['inertia/app/app.ts'],
      reload: ['resources/views/**/*.edge']
    }),
    inertia(),
    vue(),
    bitrix24UIPluginVite({
      router: 'inertia'
    })
  ]
})

Bitrix24 UI registers unplugin-auto-import and unplugin-vue-components, which will generate auto-imports.d.ts and components.d.ts type declaration files. You will likely want to gitignore these, and add them to your tsconfig.

tsconfig.app.json

{
  "include": ["src/**/*.ts", "src/**/*.tsx", "src/**/*.vue", "auto-imports.d.ts", "components.d.ts"]
}

.gitignore

# Auto-generated type declarations
auto-imports.d.ts
components.d.ts

Internally, Bitrix24 UI relies on custom alias to resolve the theme types. If you're using TypeScript, you should add an alias to your tsconfig to enable auto-completion in your vite.config.ts.

tsconfig.node.json

{
  "compilerOptions": {
    "paths": {
      "#build/b24ui": [
        "./node_modules/.b24ui-nuxt/b24ui"
      ]
    }
  }
}

tsconfig.app.json

{
  "compilerOptions": {
    "paths": {
      "#build/b24ui/*": [
        "./node_modules/.b24ui-nuxt/b24ui/*"
      ]
    }
  }
}

Use the Bitrix24 UI Vue plugin

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(b24UiPlugin)

app.mount('#app')

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Bitrix24 UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(b24UiPlugin)
      .mount(el)
  }
})

import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Bitrix24 UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(b24UiPlugin)
      .mount(el)
  }
})

Import Tailwind CSS and Bitrix24 UI in your CSS

@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

@import "tailwindcss";
@import "@bitrix24/b24ui-nuxt";

Import the CSS file in your entrypoint.

import './assets/main.css'

import { createApp } from 'vue'
import { createRouter, createWebHistory } from 'vue-router'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import App from './App.vue'

const app = createApp(App)

const router = createRouter({
  routes: [],
  history: createWebHistory()
})

app.use(router)
app.use(b24UiPlugin)

app.mount('#app')

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import { resolvePageComponent } from 'laravel-vite-plugin/inertia-helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'Laravel x Bitrix24 UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `./pages/${name}.vue`,
      import.meta.glob<DefineComponent>('./pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(b24UiPlugin)
      .mount(el)
  }
})

import '../css/app.css'
import type { DefineComponent } from 'vue'
import { createInertiaApp } from '@inertiajs/vue3'
import b24UiPlugin from '@bitrix24/b24ui-nuxt/vue-plugin'
import { resolvePageComponent } from '@adonisjs/inertia/helpers'
import { createApp, h } from 'vue'

const appName = import.meta.env.VITE_APP_NAME || 'AdonisJS x Bitrix24 UI'

createInertiaApp({
  title: title => (title ? `${title} - ${appName}` : appName),
  resolve: name =>
    resolvePageComponent(
      `../pages/${name}.vue`,
      import.meta.glob<DefineComponent>('../pages/**/*.vue')
    ),
  setup({ el, App, props, plugin }) {
    createApp({ render: () => h(App, props) })
      .use(plugin)
      .use(b24UiPlugin)
      .mount(el)
  }
})

It's recommended to install the Tailwind CSS IntelliSense extension for VSCode and add the following settings:

.vscode/settings.json

{
  "files.associations": {
    "*.css": "tailwindcss"
  },
  "editor.quickSuggestions": {
    "strings": "on"
  },
  "tailwindCSS.classAttributes": ["class", "b24ui"],
  "tailwindCSS.experimental.classRegex": [
    ["b24ui:\\s*{([^)]*)\\s*}", "(?:'|\"|`)([^']*)(?:'|\"|`)"]
  ]
}

Wrap your app with App component

<template>
  <B24App>
    <RouterView />
  </B24App>
</template>

<template>
  <B24App>
    <!-- Your content goes here -->
  </B24App>
</template>

<template>
  <B24App>
    <!-- Your content goes here -->
  </B24App>
</template>

The App component sets up global config and is required for Toast, Tooltip and programmatic overlays.

Add the `isolate` class to your root container

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Bitrix24 UI</title>
  </head>
  <body>
    <div id="app" class="isolate"></div>
    <script type="module" src="/src/main.ts"></script>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead
    @vite('resources/js/app.ts')
  </head>
  <body>
    <div class="isolate">
        @inertia
    </div>
  </body>
</html>

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1">
    @inertiaHead()
    @vite(['inertia/app/app.ts', `inertia/pages/${page.component}.vue`])
  </head>
  <body>
    @inertia({ class: 'isolate' })
  </body>
</html>

This ensures styles are scoped to your app and prevents issues with overlays and stacking contexts.

Options

You can customize Bitrix24 UI by providing options in your vite.config.ts.

`colorMode`

Use the colorMode option to enable or disable the color mode integration from @vueuse/core.

Default: true

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      colorMode: false
    })
  ]
})

`theme.prefix`

Use the theme.prefix option to configure the same prefix you set on your Tailwind CSS import. This ensures Bitrix24 UI components use the correct prefixed utility classes and CSS variables.

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      theme: {
        prefix: 'tw'
      }
    })
  ]
})

@import "tailwindcss" prefix(tw);
@import "@bitrix24/b24ui-nuxt";

This will automatically prefix all Tailwind utility classes and CSS variables in Bitrix24 UI component themes:

<!-- Without prefix -->
<button class="px-2 py-1 text-xs hover:bg-red-500/75">Button</button>

<!-- With prefix: tw -->
<button class="tw:px-2 tw:py-1 tw:text-xs tw:hover:bg-red-500/75">Button</button>

Learn more about using a prefix in the Tailwind CSS documentation.

`router`

Use the router option to configure routing integration. This is useful for applications that don't use vue-router, such as Electron apps, MPAs, or frameworks like Inertia.js or Hybridly.

Default: true

Value	Description
`true`	Uses `vue-router` for navigation with `RouterLink` component.
`false`	Disables routing integration, links render as plain `<a>` tags.
`'inertia'`	Uses Inertia.js for navigation with its `Link` component.

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      router: false
    })
  ]
})

You can provide custom navigation logic for frameworks like Hybridly by setting router: false in the Vite config and passing a function when installing the Vue plugin:

main.ts

import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'
import { router } from 'hybridly'

app.use(bitrix24UIPluginVite, {
  router: (event, { href, external }) => {
    if (external) {
      return
    }

    event.preventDefault()

    router.navigate({ url: href })
  }
})

When set to false or 'inertia', vue-router is not required as a dependency.

`scanPackages`

Use the scanPackages option to specify additional npm packages that should be scanned for components using Bitrix24 UI. This is useful when you have a shared component library that uses Bitrix24 UI components internally.

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import bitrix24UIPluginVite from '@bitrix24/b24ui-nuxt/vite'

export default defineConfig({
  plugins: [
    vue(),
    bitrix24UIPluginVite({
      scanPackages: ['@my-org/b24ui-components']
    })
  ]
})

By default, only @nuxt/ui is scanned. Use this option when your external packages contain Vue components that use Nuxt UI.