v2.12.0

CheckboxGroup

Multi-select checklist using button controls.
GitHub
Demo
Nuxt UI
CheckboxGroup avatarCheckboxGroup

Usage

Use the v-model directive to control the value of the CheckboxGroup or the default-value prop to set the initial value when you do not need to control its state.

System
Light
Dark
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>

Items

Use the items prop as an array of strings or numbers:

System
Light
Dark
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>

You can also pass an array of objects with the following properties:

  • label?: string
  • description?: string
  • value?: string
  • disabled?: boolean
  • icon?: IconComponent
  • class?: any
  • b24ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }
System

This is the first option.

Light

This is the second option.

Dark

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem } from '@bitrix24/b24ui-nuxt'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    value: 'dark'
  }
])
const value = ref([
  'system'
])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@bitrix24/b24ui-nuxt'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    value: 'dark'
  }
])
const value = ref([
  'system'
])
</script>

<template>
  <B24CheckboxGroup v-model="value" :items="items" />
</template>
When using objects, you need to reference the value property of the object in the v-model directive or the default-value prop.

Value Key

You can change the property that is used to set the value by using the value-key prop. Defaults to value.

System

This is the first option.

Light

This is the second option.

Dark

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem } from '@bitrix24/b24ui-nuxt'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    id: 'dark'
  }
])
const value = ref([
  'light'
])
</script>

<template>
  <B24CheckboxGroup v-model="value" value-key="id" :items="items" />
</template>

<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@bitrix24/b24ui-nuxt'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    id: 'dark'
  }
])
const value = ref([
  'light'
])
</script>

<template>
  <B24CheckboxGroup v-model="value" value-key="id" :items="items" />
</template>

Legend

Use the legend prop to set the legend of the CheckboxGroup.

Theme
System
Light
Dark
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    legend="Theme"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    legend="Theme"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Color

Use the color prop to change the color of the CheckboxGroup.

System
Light
Dark
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    color="air-primary-copilot"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    color="air-primary-copilot"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Variant

Use the variant prop to change the variant of the CheckboxGroup.

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    color="air-primary-copilot"
    variant="card"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    color="air-primary-copilot"
    variant="card"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Size

Use the size prop to change the size of the CheckboxGroup.

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    size="lg"
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    size="lg"
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Orientation

Use the orientation prop to change the orientation of the CheckboxGroup. Defaults to vertical.

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Indicator

Use the indicator prop to change the position or hide the indicator. Defaults to start.

An item's icon replaces the check mark while the indicator is visible, and is displayed above the label when it is hidden.
<script setup lang="ts">
import type { CheckboxGroupItem } from '@bitrix24/b24ui-nuxt'
import ThemeIcon from '@bitrix24/b24icons-vue/outline/ThemeIcon'
import SunIcon from '@bitrix24/b24icons-vue/outline/SunIcon'
import MoonIcon from '@bitrix24/b24icons-vue/outline/MoonIcon'

const items: CheckboxGroupItem[] = [
  { label: 'System', value: 'system', icon: ThemeIcon, class: 'w-24' },
  { label: 'Light', value: 'light', icon: SunIcon, class: 'w-24' },
  { label: 'Dark', value: 'dark', icon: MoonIcon, class: 'w-24' }
]
</script>

<template>
  <B24CheckboxGroup
    :items="items"
    :default-value="['system']"
    indicator="hidden"
    orientation="horizontal"
    variant="table"
  />
</template>

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    indicator="end"
    variant="card"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    indicator="end"
    variant="card"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Disabled

Use the disabled prop to disable the CheckboxGroup.

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    disabled
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <B24CheckboxGroup
    disabled
    variant="list"
    :default-value="{
      '0': 'System'
    }"
    :items="items"
  />
</template>

Examples

Settings layout

Use the card variant together with the #label slot to render a settings-style picker where each option has a title, description, a "Learn more" link and a preview image. The label slot renders inside a <span>, so any phrasing-content layout (flex, link, image) works.

<script setup lang="ts">
type CapabilityItem = {
  value: string
  title: string
  text: string
  href: string
}

const value = ref<string[]>(['columns'])

const items: CapabilityItem[] = [
  {
    value: 'columns',
    title: 'In columns',
    text: 'Pick this for resources that must always be visible to the manager. These are the primary resources the schedule is built around.',
    href: 'https://helpdesk.bitrix24.com/'
  },
  {
    value: 'list',
    title: 'In a secondary list',
    text: 'Pick this for resources that are booked only in addition to a primary one. For instance, when specialists are the primary resource, equipment goes into the secondary list.',
    href: 'https://helpdesk.bitrix24.com/'
  }
]
</script>

<template>
  <B24CheckboxGroup
    v-model="value"
    variant="card"
    size="md"
    :items="items"
    class="w-full max-w-2xl"
  >
    <template #label="{ item }">
      <span class="flex gap-3 items-start w-full">
        <span class="flex-1 min-w-0 flex flex-col gap-1">
          <span class="text-(length:--ui-font-size-md) font-(--ui-font-weight-medium)">
            {{ item.title }}
          </span>
          <span class="text-(length:--ui-font-size-sm) text-description font-(--ui-font-weight-regular)">
            {{ item.text }}
          </span>
          <B24Link
            :to="item.href"
            target="_blank"
            class="self-start mt-1 text-(length:--ui-font-size-sm)"
            @click.stop
          >
            Learn more
          </B24Link>
        </span>
        <Placeholder class="hidden sm:flex shrink-0 w-[120px] h-[72px] text-(length:--ui-font-size-xs) text-description">
          Preview
        </Placeholder>
      </span>
    </template>
  </B24CheckboxGroup>
</template>

<script setup lang="ts">
import { ref } from 'vue'

type CapabilityItem = {
  value: string
  title: string
  text: string
  href: string
}

const value = ref<string[]>(['columns'])

const items: CapabilityItem[] = [
  {
    value: 'columns',
    title: 'In columns',
    text: 'Pick this for resources that must always be visible to the manager. These are the primary resources the schedule is built around.',
    href: 'https://helpdesk.bitrix24.com/'
  },
  {
    value: 'list',
    title: 'In a secondary list',
    text: 'Pick this for resources that are booked only in addition to a primary one. For instance, when specialists are the primary resource, equipment goes into the secondary list.',
    href: 'https://helpdesk.bitrix24.com/'
  }
]
</script>

<template>
  <B24CheckboxGroup
    v-model="value"
    variant="card"
    size="md"
    :items="items"
    class="w-full max-w-2xl"
  >
    <template #label="{ item }">
      <span class="flex gap-3 items-start w-full">
        <span class="flex-1 min-w-0 flex flex-col gap-1">
          <span class="text-(length:--ui-font-size-md) font-(--ui-font-weight-medium)">
            {{ item.title }}
          </span>
          <span class="text-(length:--ui-font-size-sm) text-description font-(--ui-font-weight-regular)">
            {{ item.text }}
          </span>
          <B24Link
            :to="item.href"
            target="_blank"
            class="self-start mt-1 text-(length:--ui-font-size-sm)"
            @click.stop
          >
            Learn more
          </B24Link>
        </span>
        <Placeholder class="hidden sm:flex shrink-0 w-[120px] h-[72px] text-(length:--ui-font-size-xs) text-description">
          Preview
        </Placeholder>
      </span>
    </template>
  </B24CheckboxGroup>
</template>

Build a rich checkbox-card settings picker (preview + description + link).

Stop the click from toggling the checkbox when the user follows the inline link by adding @click.stop to it.
Same recipe works for single-select — see RadioGroup → Settings layout. For icon-and-description grids (no preview image), reach for B24PageCardGroup instead.

API

Props

Prop Default Type
as'div'any

The element or component this component should render as.

legend string
valueKey'value' VK

When items is an array of objects, select the field to use as the value.

labelKey'label' keyof Extract<NestedItem<T>, object> & string | DotPathKeys<Extract<NestedItem<T>, object>>

When items is an array of objects, select the field to use as the label.

descriptionKey'description' keyof Extract<NestedItem<T>, object> & string | DotPathKeys<Extract<NestedItem<T>, object>>

When items is an array of objects, select the field to use as the description.

items T
modelValue GetItemValue<T, VK, undefined, NestedItem<T>>[]

The controlled value of the CheckboxGroup. Can be bind as v-model.

defaultValue GetItemValue<T, VK, undefined, NestedItem<T>>[]

The value of the CheckboxGroup when initially rendered. Use when you do not need to control the state of the CheckboxGroup.

size'md' "xs" | "sm" | "md" | "lg"
variant'list' "card" | "list" | "table"
orientation'vertical' "horizontal" | "vertical"

The orientation the checkbox buttons are laid out.

disabledboolean

When true, prevents the user from interacting with the checkboxes

loopfalseboolean

Whether keyboard navigation should loop around

name string

The name of the field. Submitted with its owning form as part of a name/value pair.

requiredboolean

When true, indicates that the user must set the value before the owning form can be submitted.

iconicons.checkIconComponent

The icon displayed when checked, or above the label when indicator is hidden.

color'air-primary'"air-primary" | "air-primary-success" | "air-primary-alert" | "air-primary-warning" | "air-primary-copilot"
highlightboolean

Highlight the ring color like a focus state.

indicator'start' "start" | "end" | "hidden"

Position of the indicator.

b24ui { root?: SlotClass; fieldset?: SlotClass; legend?: SlotClass; item?: SlotClass; } & { root?: SlotClass; base?: SlotClass; indicator?: SlotClass; container?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }

Slots

Slot Type
legend{}
label{ item: Exclude<T[number] & { id: string; }, AcceptableValue>; }
description{ item: Exclude<T[number] & { id: string; }, AcceptableValue>; }

Emits

Event Type
update:modelValue[value: GetItemValue<T, VK, undefined, NestedItem<T>>[]]
change[event: Event]

Theme

https://github.com/bitrix24/b24ui/tree/main/src/theme/checkbox-group.ts
export default {
  slots: {
    root: 'relative',
    fieldset: 'flex gap-x-2',
    legend: 'mb-1.5 block text-label',
    item: ''
  },
  variants: {
    orientation: {
      horizontal: {
        fieldset: 'flex-row'
      },
      vertical: {
        fieldset: 'flex-col'
      }
    },
    color: {
      'air-primary': {
        item: 'style-filled'
      },
      'air-primary-success': {
        item: 'style-filled-success'
      },
      'air-primary-alert': {
        item: 'style-filled-alert'
      },
      'air-primary-copilot': {
        item: 'style-filled-copilot'
      },
      'air-primary-warning': {
        item: 'style-filled-warning'
      },
      default: {
        item: 'style-old-default'
      },
      danger: {
        item: 'style-old-danger'
      },
      success: {
        item: 'style-old-success'
      },
      warning: {
        item: 'style-old-warning'
      },
      primary: {
        item: 'style-old-primary'
      },
      secondary: {
        item: 'style-old-secondary'
      },
      collab: {
        item: 'style-old-collab'
      },
      ai: {
        item: 'style-old-ai'
      }
    },
    variant: {
      list: {},
      card: {
        item: 'cursor-pointer items-start border border-(--ui-color-design-outline-na-stroke) bg-(--ui-color-design-outline-na-bg) has-data-[state=checked]:border-(--b24ui-border-color)'
      },
      table: {
        item: 'cursor-pointer border border-(--ui-color-design-outline-na-stroke) bg-(--ui-color-design-outline-na-bg) has-data-[state=checked]:bg-(--b24ui-background)/24 has-data-[state=checked]:border-(--b24ui-border-color) has-data-[state=checked]:text-(--b24ui-color) has-data-[state=checked]:z-[1]'
      }
    },
    size: {
      xs: {
        fieldset: 'gap-x-[12px] gap-y-[4px]',
        legend: 'text-(length:--ui-font-size-xs)'
      },
      sm: {
        fieldset: 'gap-x-[14px] gap-y-[6px]',
        legend: 'text-(length:--ui-font-size-xs)'
      },
      md: {
        fieldset: 'gap-x-[16px] gap-y-2',
        legend: 'text-(length:--ui-font-size-sm)'
      },
      lg: {
        fieldset: 'gap-x-[16px] gap-y-2',
        legend: 'text-(length:--ui-font-size-sm)'
      }
    },
    disabled: {
      true: {}
    },
    required: {
      true: {
        label: "after:content-['*'] after:ms-0.5 after:text-(--ui-color-accent-main-alert)"
      }
    }
  },
  compoundVariants: [
    {
      size: 'xs',
      variant: 'card',
      class: {
        item: 'px-[13px] py-[7px] rounded-(--ui-border-radius-xs)'
      }
    },
    {
      size: 'sm',
      variant: 'card',
      class: {
        item: 'px-[13px] py-[9px] rounded-(--ui-border-radius-sm)'
      }
    },
    {
      size: 'md',
      variant: 'card',
      class: {
        item: 'px-[17px] py-[10px] rounded-(--ui-border-radius-md)'
      }
    },
    {
      size: 'lg',
      variant: 'card',
      class: {
        item: 'px-[23px] py-[12px] rounded-(--ui-border-radius-md)'
      }
    },
    {
      size: 'xs',
      variant: 'table',
      class: {
        item: 'px-[13px] py-[7px]'
      }
    },
    {
      size: 'sm',
      variant: 'table',
      class: {
        item: 'px-[13px] py-[9px]'
      }
    },
    {
      size: 'md',
      variant: 'table',
      class: {
        item: 'px-[17px] py-[10px]'
      }
    },
    {
      size: 'lg',
      variant: 'table',
      class: {
        item: 'px-[23px] py-[12px]'
      }
    },
    {
      size: 'xs',
      variant: 'table',
      orientation: 'horizontal',
      class: {
        item: 'first-of-type:rounded-s-(--ui-border-radius-xs) last-of-type:rounded-e-(--ui-border-radius-xs)',
        fieldset: 'gap-0 -space-x-px'
      }
    },
    {
      size: 'xs',
      variant: 'table',
      orientation: 'vertical',
      class: {
        item: 'first-of-type:rounded-t-(--ui-border-radius-xs) last-of-type:rounded-b-(--ui-border-radius-xs)',
        fieldset: 'gap-0 -space-y-px'
      }
    },
    {
      size: 'sm',
      variant: 'table',
      orientation: 'horizontal',
      class: {
        item: 'first-of-type:rounded-s-(--ui-border-radius-sm) last-of-type:rounded-e-(--ui-border-radius-sm)',
        fieldset: 'gap-0 -space-x-px'
      }
    },
    {
      size: 'sm',
      variant: 'table',
      orientation: 'vertical',
      class: {
        item: 'first-of-type:rounded-t-(--ui-border-radius-sm) last-of-type:rounded-b-(--ui-border-radius-sm)',
        fieldset: 'gap-0 -space-y-px'
      }
    },
    {
      size: [
        'lg',
        'md'
      ],
      variant: 'table',
      orientation: 'horizontal',
      class: {
        item: 'first-of-type:rounded-s-(--ui-border-radius-md) last-of-type:rounded-e-(--ui-border-radius-md)',
        fieldset: 'gap-0 -space-x-px'
      }
    },
    {
      size: [
        'lg',
        'md'
      ],
      variant: 'table',
      orientation: 'vertical',
      class: {
        item: 'first-of-type:rounded-t-(--ui-border-radius-md) last-of-type:rounded-b-(--ui-border-radius-md)',
        fieldset: 'gap-0 -space-y-px'
      }
    },
    {
      variant: 'table',
      disabled: true,
      class: {
        item: 'cursor-not-allowed'
      }
    }
  ],
  defaultVariants: {
    size: 'md',
    variant: 'list',
    color: 'air-primary'
  }
}

Checkbox

A toggle input for marking as checked or unchecked.

ColorPicker

A color picker component.