Installation

Setup

Use our Nuxt Starter

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

Create a new project locally by running the following command:

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

Add to a Nuxt project

pnpm add @bitrix24/b24ui-nuxt

yarn add @bitrix24/b24ui-nuxt

npm install @bitrix24/b24ui-nuxt

bun add @bitrix24/b24ui-nuxt

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt']
})

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

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css']
})

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

<template>
  <B24App>
    <NuxtPage />
  </B24App>
</template>

Options

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

colorMode

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

• Default: true

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    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.

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    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>

mdc

Use the mdc option to force the import of Bitrix24 UI <Prose> components even if @nuxtjs/mdc or @nuxt/content is not installed.

• Default: true

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    mdc: false
  }
})

content

Use the content option to force the import of Bitrix24 UI <Prose> and <B24Content> components even if @nuxt/content is not installed (@nuxtjs/mdc is installed by @nuxt/content).

• Default: false

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    content: true
  }
})

experimental.componentDetection

Use the experimental.componentDetection option to enable automatic component detection for tree-shaking. This feature scans your source code to detect which components are actually used and only generates the necessary CSS for those components (including their dependencies).

• Default: false
• Type: boolean | string[]

Enable automatic detection:

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    experimental: {
      componentDetection: true
    }
  }
})

Include additional components for dynamic usage:

export default defineNuxtConfig({
  modules: ['@bitrix24/b24ui-nuxt'],
  css: ['~/assets/css/main.css'],
  b24ui: {
    experimental: {
      componentDetection: ['Modal', 'Dropdown', 'Popover']
    }
  }
})