Color Mode - Bitrix24 UI for Vue

Overview

Bitrix24 UI provides a flexible color mode system built on VueUse. It supports five distinct modes:

light – classic light theme (default)
dark – classic dark theme
edge-light – light theme with a light background and customizable background image
edge-dark – light theme with a dark background and customizable background image
auto – follows the user’s OS preference (switches between light/dark based on prefers-color-scheme)

Additionally, the base-mode CSS class is applied when the auto mode is active. It maps edge-light and edge-dark to either light or dark depending on the OS preference, while preserving their custom background variables.

The system also respects the platform (mobile, desktop, web) and loads separate design tokens for each platform when the corresponding data-platform attribute is present on the <html> element.

Usage

Bitrix24 UI automatically registers the VueUse composable, so no additional setup is required.

Components

You can use the built-in ColorModeAvatar or ColorModeImage components to display different images for each color mode. The ColorModeButton, ColorModeSwitch and ColorModeSelect components let users switch between all available modes (light, dark, edge-light, edge-dark, auto).

Use the Bitrix24 UI composable useColorMode to create your own color mode management component.

ColorModeButton.vue

<script setup lang="ts">
import { useColorMode } from '@bitrix24/b24ui-nuxt/composables'
import SunIconAir from '@bitrix24/b24icons-vue/outline/SunIcon'
import MoonIconAir from '@bitrix24/b24icons-vue/outline/MoonIcon'

const colorMode = useColorMode()

const isDark = computed({
  get() {
    return colorMode.value === 'dark'
  },
  set(_isDark: boolean) {
    colorMode.preference = _isDark ? 'dark' : 'light'
  }
})
</script>

<template>
  <B24Button
    :icon="isDark ? MoonIconAir : SunIconAir"
    :aria-label="`Switch to ${isDark ? 'light' : 'dark'} mode`"
    @click="isDark = !isDark"
  />
</template>

Configuration

You can configure the color-mode behavior through the options of the Vite plugin in your vite.config.ts:

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({
      // Enable/disable the color-mode plugin entirely
      colorMode: true,
      // Initial color mode when no stored preference exists
      colorModeInitialValue: 'light',               // 'auto' | 'dark' | 'light' | 'edge-dark' | 'edge-light'
      // Which mode should be treated as the “light” mode
      colorModeTypeLight: 'light',                  // 'light' | 'edge-dark' | 'edge-light'
      // Storage key for persisting the user‘s preference (null disables persistence)
      colorModeStorageKey: 'vueuse-color-scheme'    // string | null
    })
  ]
})

Options explained

colorMode (boolean, default true)
Turns the color-mode integration on or off. When disabled, useColorMode() returns a stub object with forced: true.
colorModeInitialValue ('auto' | 'dark' | 'light' | 'edge-dark' | 'edge-light', default 'light')
The mode that will be used when the user hasn’t yet expressed a preference (no stored value in localStorage/sessionStorage).
If you set colorModeTypeLight to 'edge-dark' and colorModeInitialValue to 'edge-dark', the site will start in the edge-dark theme.
colorModeTypeLight ('light' | 'edge-dark' | 'edge-light', default 'light')
Defines which mode is treated as the “light” variant. This affects the light/dark toggle: when the user switches to “light”, the system will actually switch to the mode specified here.
Example: colorModeTypeLight: 'edge-dark' makes the light preference map to the edge-dark theme.
colorModeStorageKey (string | null, default 'vueuse-color-scheme')
The key used to persist the user‘s preference in localStorage/sessionStorage. Set to null to disable persistence (the choice will be lost on page reload).

All these options can also be provided via app.config.ts (they are merged with the plugin options).

Customizing background images

The edge-light and edge-dark modes are designed to work with custom background images. You can override the default background variables by adding CSS rules in your main.css file.

Example: setting a background for `edge-dark`

src/assets/css/main.css

@layer base {
  .edge-dark {
    --air-theme-bg-image: url(/bg/edge-dark-v4.jpeg);
    --air-theme-bg-position: 0 0;
    --air-theme-bg-size: cover;
    --air-theme-bg-repeat: no-repeat;
    --air-theme-bg-attachment: fixed;
    --air-theme-bg-color: #162345;
  }
}

Example: setting a background for `edge-light`

src/assets/css/main.css

@layer base {
  .edge-light {
    --air-theme-bg-image: url(/bg/edge-light-v1.svg);
    --air-theme-bg-position: 0 0;
    --air-theme-bg-size: 240px 240px;
    --air-theme-bg-repeat: repeat;
    --air-theme-bg-attachment: fixed;
    --air-theme-bg-color: #f1dbdb87;
  }
}

The same variables can be overridden per-component using Tailwind’s arbitrary variants:

SlideoverSimpleListElementsExample.vue

<B24Slideover
  :b24ui="{
    content: [
      'air-custom-bg',
      'edge-dark',
      'edge-dark:[--air-theme-bg-color:#7c235b]',
      'edge-dark:[--air-theme-bg-size:cover]',
      'edge-dark:[--air-theme-bg-image:url(/bg/edge-dark-v2.jpg)]'
    ].join(' ')
  }"
>
  <!-- ... -->
</B24Slideover>

Platform-specific tokens

If your application runs inside the Bitrix24 mobile or desktop app, the <html> element receives a data-platform="bitrix-mobile" or data-platform="bitrix-desktop" attribute. Separate design-token files (*_mobile_*.css, *_desktop_*.css) are automatically loaded for these platforms, adapting the color palette to the host environment.