Checkbox

TuiCheckbox is used to perform multiple selections from a group of options. While it shares a similar appearance system with the Radio component, its bound value is an array. It supports quantity limits, button styles, card styles, and highly customizable slot content.

Basic Usage

Data-Driven Rendering (Options)

Pass a configuration array through the options property.

• modelValue: Must be bound to an array.

<script setup>
import { ref } from 'vue';

const checkedList = ref(['A', 'B']);
const options = [
  { label: 'Option A', value: 'A' },
  { label: 'Option B', value: 'B' },
  { label: 'Disabled Item', value: 'C', disabled: true }
];
</script>

<template>
  <TuiCheckbox v-model="checkedList" :options="options" />
</template>

Slot Customization (Slot)

Construct using the <TuiCheckboxItem> sub-component.

<template>
  <TuiCheckbox v-model="checkedList">
    <TuiCheckboxItem value="apple">Apple</TuiCheckboxItem>
    <TuiCheckboxItem value="banana">Banana</TuiCheckboxItem>
  </TuiCheckbox>
</template>

Appearance Styles

Switch styles via the appearance property.

Simple Style (Simple)

The default style, featuring standard square checkboxes.

Button Style (Button)

A solid button style where the background is filled when selected.

• separable: Set to true to add spacing between buttons.

<template>
  <TuiCheckbox appearance="button" v-model="vals" :options="opts" />
  
  <TuiCheckbox appearance="button" separable v-model="vals" :options="opts" />
</template>

Card Style (ButtonPlain)

An outlined card style where the border is highlighted when selected.

<TuiCheckbox appearance="buttonPlain" v-model="vals" :options="opts" />

Layout and Direction

• direction: 'v' (vertical) / 'h' (horizontal).
• textDirection: Setting to 'v' allows the option text to be arranged vertically.

<TuiCheckbox direction="v" :options="options" />

Quantity Limits

Use the max property to limit the maximum number of items a user can select. When the limit is reached, unselected options will automatically become disabled.

<template>
  <TuiCheckbox 
    :max="2" 
    v-model="checkedCities" 
    :options="cities" 
  />
</template>

Icon Customization

Similar to the Radio component, it supports custom icon state switching. Pass an array in the format ['Unselected Icon', 'Selected Icon'].

<script setup>
const iconOpts = [
  { label: 'Favorite', value: 1, icon: ['tui-icon ti-star', 'tui-icon tis-star'] },
  { label: 'Like', value: 2, icon: ['tui-icon ti-thumb-up', 'tui-icon tis-thumb-up'] }
];
</script>

<template>
  <TuiCheckbox appearance="buttonPlain" :options="iconOpts" />
</template>

Advanced Customization

Case: Theme Palette Selector

Utilize defaultIcon="false" to hide the default checkbox and use slots to implement a completely customized interaction interface.

<template>
  <TuiCheckbox v-model="selectedThemes" :defaultIcon="false" class="theme-checkbox">
    <TuiCheckboxItem 
      v-for="item in themeOptions" 
      :key="item.value" 
      :value="item.value"
      class="theme-item"
    >
      <div class="color-view">
        <i class="tui-icon ti-check check-mark"></i>
        <div class="color-stripe" :style="{ background: item.color1 }"></div>
        <div class="color-stripe" :style="{ background: item.color2 }"></div>
      </div>
    </TuiCheckboxItem>
  </TuiCheckbox>
</template>

<style lang="less" scoped>
.theme-checkbox {
  .theme-item {
    margin-right: 10px;
    // Selected state style
    &.is-active {
      .check-mark { opacity: 1; transform: translate(-50%, -50%) scale(1); }
    }
    
    .color-view {
      position: relative; width: 40px; height: 40px; border-radius: 6px; overflow: hidden;
      .color-stripe { height: 50%; width: 100%; }
      .check-mark {
        position: absolute; left: 50%; top: 50%; color: #fff; opacity: 0;
        transform: translate(-50%, -50%) scale(0.5); transition: all 0.2s;
        text-shadow: 0 1px 2px rgba(0,0,0,0.3);
      }
    }
  }
}
</style>

API Reference

TuiCheckbox Props

Property	Type	Default	Description
modelValue	Array	-	Required. Array of bound values.
options	Array	[]	Data source.
max	Number	-	Maximum selectable quantity.
appearance	String	'simple'	Appearance style. Options: simple, button, buttonPlain.
direction	String	'h'	Arrangement direction. Options: h, v.
size	String	'default'	Size. Options: large, default, small.
defaultIcon	Boolean	true	Whether to show the default checkbox icon.
separable	Boolean	false	Whether buttons are separated in button mode.
align	String	null	Alignment method.
textDirection	String	null	Text arrangement direction.
itemMaxWidth	Number/String	-	Maximum width of an option.
disabled	Boolean	false	Global disabled state.
className	String	-	Custom class name.

TuiCheckbox Events

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value: Array)
change	Triggered when the selection state changes.	(value: Array)

TuiCheckboxItem Props

Property	Type	Default	Description
value	String/Number/Boolean	Required	The value of the option.
icon	String/Array	null	Icon configuration.
disabled	Boolean	false	Whether to disable this item.