Customize components

Learn how to customize Bitrix24 UI components with the Tailwind Variants API for advanced, flexible, and maintainable styling.

Tailwind Variants

Bitrix24 UI components are styled using the Tailwind Variants API, which provides a powerful way to create variants and manage component styles.

Slots

Components can have multiple slots, each representing a distinct HTML element or section within the component. These slots allow for flexible content insertion and styling.

Let's take the Card component as an example which has multiple slots:

export default {
  slots: {
    root: 'bg-(--ui-color-design-filled-bg) border border-(--ui-color-design-filled-stroke) border-(length:--ui-design-filled-stroke-weight) text-(--ui-color-design-filled-content)',
    header: 'p-[24px] sm:px-[22px] sm:py-[15px]',
    body: 'p-[24px] sm:px-[22px] sm:py-[15px]',
    footer: 'p-[24px] sm:px-[22px] sm:py-[15px]'
  }
}

<template>
  <div :class="b24ui.root({ class: [props.b24ui?.root, props.class] })">
    <div :class="b24ui.header({ class: props.b24ui?.header })">
      <slot name="header" />
    </div>

    <div :class="b24ui.body({ class: props.b24ui?.body })">
      <slot />
    </div>

    <div :class="b24ui.footer({ class: props.b24ui?.footer })">
      <slot name="footer" />
    </div>
  </div>
</template>

Some components don't have slots, they are just composed of a single root element. In this case, the theme only defines the base slot like the Container component for example:

export default {
  base: 'w-full max-w-[1280px] mx-auto px-[22px]'
}

<template>
  <div :class="container({ class: props.class })">
    <slot />
  </div>
</template>

Components without slots don't have a b24ui prop, only the class prop is available to override styles.

Variants

Components support variants, which allow you to dynamically adjust the styles of different slots based on component props.

For example, the Avatar component uses a size variant to control its appearance:

src/theme/avatar.ts

export default {
  slots: {
    root: 'air-secondary-accent inline-flex items-center justify-center shrink-0 select-none rounded-full align-middle bg-(--ui-color-base-8) ring ring-(--ui-color-base-7)',
    image: 'h-full w-full rounded-[inherit] object-cover'
  },
  variants: {
    size: {
      sm: {
        root: 'size-[28px] text-(length:--ui-font-size-xs)/(--ui-font-line-height-reset)'
      },
      md: {
        root: 'size-[32px] text-(length:--ui-font-size-sm)/(--ui-font-line-height-reset)'
      },
      lg: {
        root: 'size-[42px] text-(length:--ui-font-size-2xl)/(--ui-font-line-height-reset)'
      }
    }
  },
  defaultVariants: {
    size: 'md'
  }
}

This way, the size prop will apply the corresponding styles to the root slot:

size

{
  "wait": "Loading client-side content..."
}

Default Variants

The defaultVariants property sets the default value for each variant when no prop is passed.

For example, the Avatar component has its default size set to md:

src/theme/avatar.ts

export default {
  slots: {
    root: 'air-secondary-accent inline-flex items-center justify-center shrink-0 select-none rounded-full align-middle bg-(--ui-color-base-8) ring ring-(--ui-color-base-7)',
    image: 'h-full w-full rounded-[inherit] object-cover'
  },
  variants: {
    size: {
      sm: {
        root: 'size-[28px] text-(length:--ui-font-size-xs)/(--ui-font-line-height-reset)'
      },
      md: {
        root: 'size-[32px] text-(length:--ui-font-size-sm)/(--ui-font-line-height-reset)'
      },
      lg: {
        root: 'size-[42px] text-(length:--ui-font-size-2xl)/(--ui-font-line-height-reset)'
      }
    }
  },
  defaultVariants: {
    size: 'md'
  }
}

Compound Variants

Some components use the compoundVariants property to apply classes when multiple variant conditions are met at the same time.

For example, the Alert component uses the compoundVariants property to apply classes for a specific color and inverted combination:

src/theme/button.ts

export default {
  slots: {
    root: [
      'relative overflow-hidden w-full flex',
      'text-(--b24ui-color)',
      'bg-(--b24ui-background)',
      'border-(--b24ui-border-color) border-(length:--b24ui-border-width)',
      'rounded-(--ui-border-radius-md)'
    ].join(' ')
  },
  variants: {
    color: {
      'air-primary': { root: 'style-filled' },
      'air-primary-success': { root: 'style-filled-success' }
    },
    inverted: {
      true: '',
      false: ''
    }
  },
  compoundVariants: [
    {
      inverted: true,
      color: 'air-primary',
      class: {
        root: 'style-filled-inverted'
      }
    },
    {
      inverted: true,
      color: 'air-primary-success',
      class: {
        root: 'style-filled-success-inverted'
      }
    }
  ],
  defaultVariants: {
    color: 'primary',
    variant: 'solid'
  }
}

Customize theme

You have multiple ways to customize the appearance of Bitrix24 UI components, you can do it for all components at once or on a per-component basis.

Tailwind Variants uses tailwind-merge under the hood to merge classes so you don't have to worry about conflicting classes.

You can explore the theme for each component in two ways:

Check the Theme section in the documentation of each individual component.
Browse the source code directly in the GitHub repository at src/theme.

`b24ui` prop

You can override a component's slots using the b24ui prop. This takes priority over both global config and resolved variants.

useDropdown

{
  "wait": "Loading client-side content..."
}

In this example, the trailingIcon slot is overwritten with size-10 even though the md size variant would apply a size-(--ui-btn-icon-size) class to it.

`class` prop

The class prop allows you to override the classes of the root or base slot. This takes priority over both global config and resolved variants.

class

{
  "wait": "Loading client-side content..."
}

In this example, the font-bold class will override the default font-medium class on this button.

CSS Variables

Bitrix24 UI uses CSS variables as design tokens for flexible, consistent theming with built-in light and dark mode support.

Icons

Bitrix24 UI integrates with @bitrix24/b24icons to access over 1,400+ icons.