BreezeUI
  • English

    • Checkbox

    A control that allows the user to toggle between checked and not checked.

    Component Features

    • ☑️ Single & Group: Supports single checkbox and BrCheckboxGroup for multiple options.
    • 🔲 Indeterminate State: Supports indeterminate state for parent-child selection.
    • 📏 Multiple Sizes: Supports xs, sm, md, lg, xl, 2xl size specs.
    • ❌ Disabled State: Supports disabled prop for both single and group mode.
    • ⚠️ Error State: Supports error prop to display error state.
    • 🏷️ Custom Label: Supports custom label content via slots.
    • 🎨 Theme Customization: Based on BrConfigProvider for global theming and TailwindCSS local overrides.

    Basic Usage

    <script setup lang="ts">
import { ref } from 'vue'
import { BrCheckbox } from '@breezeui/vue'

const checked = ref(false)
</script>

<template>
  <div class="flex items-center space-x-2">
    <BrCheckbox id="terms" v-model="checked" label="Accept terms and conditions" />
  </div>
</template>

    Checkbox Group

    Use BrCheckboxGroup to group multiple checkboxes.

    <script setup lang="ts">
import { ref } from 'vue'
import { BrCheckbox, BrCheckboxGroup } from '@breezeui/vue'

const selected = ref(['apple'])
</script>

<template>
  <div class="space-y-4">
    <BrCheckboxGroup v-model="selected">
      <BrCheckbox value="apple" label="Apple" />
      <BrCheckbox value="banana" label="Banana" />
      <BrCheckbox value="cherry" label="Cherry" />
    </BrCheckboxGroup>
    
    <div class="text-sm text-muted-foreground">
      Selected: {{ selected }}
    </div>
  </div>
</template>

    Indeterminate State

    The indeterminate state is used when a checkbox's state is neither checked nor unchecked.

    <script setup lang="ts">
import { ref, watch } from 'vue'
import { BrCheckbox, BrCheckboxGroup } from '@breezeui/vue'

const checkAll = ref(false)
const indeterminate = ref(true)
const checkedCities = ref(['Shanghai', 'Beijing'])
const cities = ['Shanghai', 'Beijing', 'Guangzhou', 'Shenzhen']

const handleCheckAllChange = (val: boolean) => {
  indeterminate.value = false
  if (val) {
    checkedCities.value = [...cities]
  } else {
    checkedCities.value = []
  }
}

watch(checkedCities, (val) => {
  const checkedCount = val.length
  const citiesCount = cities.length
  checkAll.value = checkedCount === citiesCount
  indeterminate.value = checkedCount > 0 && checkedCount < citiesCount
})
</script>

<template>
  <div class="space-y-4">
    <BrCheckbox
      :model-value="checkAll"
      :indeterminate="indeterminate"
      @update:model-value="handleCheckAllChange"
    >
      Check all
    </BrCheckbox>
    
    <div class="ml-6">
      <BrCheckboxGroup v-model="checkedCities" class="flex flex-col gap-2">
        <BrCheckbox v-for="city in cities" :key="city" :value="city" :label="city" />
      </BrCheckboxGroup>
    </div>
  </div>
</template>

    Sizes

    We provide a default set of sizes that you can control via the size prop.

    <script setup lang="ts">
import { ref } from 'vue'
import { BrCheckbox } from '@breezeui/vue'

const checked = ref(true)
</script>

<template>
  <div class="flex flex-col gap-4">
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="xs" label="Extra Small (xs)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="sm" label="Small (sm)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="default" label="Default (md)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="lg" label="Large (lg)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="xl" label="Extra Large (xl)" />
    </div>
    <div class="flex items-center gap-2">
      <BrCheckbox v-model="checked" size="2xl" label="2X Large (2xl)" />
    </div>
  </div>
</template>

    Disabled State

    <script setup lang="ts">
import { BrCheckbox, BrCheckboxGroup } from '@breezeui/vue'
</script>

<template>
  <div class="space-y-4">
    <div class="flex items-center space-x-2">
      <BrCheckbox disabled label="Disabled Checkbox" />
    </div>
    <div class="flex items-center space-x-2">
      <BrCheckbox disabled :model-value="true" label="Disabled Checked" />
    </div>
    
    <div class="space-y-2">
      <p class="text-sm font-medium">Disabled Group</p>
      <BrCheckboxGroup disabled :model-value="['apple']">
        <BrCheckbox value="apple" label="Apple" />
        <BrCheckbox value="banana" label="Banana" />
      </BrCheckboxGroup>
    </div>
  </div>
</template>

    Theming

    Global Customization (BrConfigProvider)

    You can override default CSS variables via the theme prop of BrConfigProvider.

    <template>
  <BrConfigProvider :theme="{ primary: '#10B981', radius: 0.5 }">
    <BrCheckbox v-model="checked" label="Custom Theme" />
  </BrConfigProvider>
</template>

    Local Customization (TailwindCSS)

    You can directly override styles using TailwindCSS utility classes on the wrapper or via deep selectors if needed, but wrapper class is usually sufficient for layout.

    <template>
  <BrCheckbox class="mb-4" label="Margin Bottom" />
</template>

    API

    BrCheckbox

    Props

    NameTypeDefaultDescription
    modelValueboolean | string | numberundefinedBinding value
    valuestring | number | booleanundefinedValue of the checkbox (used in group)
    disabledbooleanfalseWhether the checkbox is disabled
    indeterminatebooleanfalseWhether the checkbox is in indeterminate state
    labelstringundefinedLabel text
    idstringundefinedInput id
    namestringundefinedInput name
    requiredbooleanfalseWhether the checkbox is required
    errorbooleanfalseWhether the checkbox is in error state
    size'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'default''default'Size of the checkbox

    Emits

    NameDescriptionParameters
    update:modelValueUpdate model value(value: boolean | string | number)
    changeChange event(value: boolean | string | number)

    Slots

    NameDescription
    defaultLabel content
    iconCustom icon slot

    BrCheckboxGroup

    Props

    NameTypeDefaultDescription
    modelValue(string | number)[][]Binding value array
    disabledbooleanfalseWhether the group is disabled
    size'sm' | 'default' | 'lg''default'Size of all checkboxes in the group
    namestringundefinedName attribute for all checkboxes

    Emits

    NameDescriptionParameters
    update:modelValueUpdate model value(value: (string | number)[])
    changeChange event(value: (string | number)[])