Checkbox
Select multiple options from a set of alternatives.
Basic Usage
Used alone, it can toggle between two states. Bind a Boolean variable with v-model.
Disabled
Use the disabled prop to control the checkbox disabled state.
Checkbox Group
Useful when binding multiple checkboxes to the same array.
Checked: [ "Option A" ]
Indeterminate
The indeterminate prop represents the checkbox's indeterminate state, commonly used to implement a "select all" effect.
With Border
Use the border prop to render checkboxes with borders.
Sizes
Use the size prop to set checkbox sizes.
Limit Selection Count
Use min and max props to limit the number of items that can be checked.
Min 1, Max 2
Custom Check Values
Use true-value and false-value props to customize the checked and unchecked values.
Bound value type: string, value: no
Use in Nuxt
The Checkbox component fully supports SSR rendering in Nuxt 3/4. Components are auto-imported in Nuxt projects.
SSR Notes:
- ✅ Single checkbox and checkbox groups fully supported
- ✅ All visual states (checked, disabled, border, etc.) are consistent in SSR
- ✅ Indeterminate state styling supported
SSR Safety
The Checkbox component has passed comprehensive SSR testing, ensuring server-rendered results are consistent with client-side hydrated structures, avoiding Hydration warnings.
API
Checkbox Props
| Prop | Description | Type | Default |
|---|---|---|---|
| model-value / v-model | Binding value | string | number | boolean | — |
| value | Value when checked (used in checkbox-group) | string | number | boolean | — |
| label | Display text (if no default slot) | string | — |
| true-value | Value when checked | string | number | boolean | true |
| false-value | Value when unchecked | string | number | boolean | false |
| disabled | Whether disabled | boolean | false |
| indeterminate | Set indeterminate state (style only) | boolean | false |
| border | Whether to show border | boolean | false |
| size | Checkbox size | 'large' | 'default' | 'small' | 'default' |
| name | Native name attribute | string | — |
| checked | Whether currently checked | boolean | — |
| id | Input id | string | — |
| tabindex | Input tabindex | string | number | — |
Checkbox Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered when binding value changes | (value: string | number | boolean) => void |
Checkbox Slots
| Slot Name | Description |
|---|---|
| default | Custom default content |
Checkbox Expose
| Name | Description | Type |
|---|---|---|
| ref | Native input element | Ref<HTMLInputElement> |
| checked | Whether checked | boolean |
| focus | Focus the input | () => void |
| blur | Blur the input | () => void |
CheckboxGroup Props
| Prop | Description | Type | Default |
|---|---|---|---|
| model-value / v-model | Binding value | Array<string | number | boolean> | [] |
| size | Checkbox group size | 'large' | 'default' | 'small' | — |
| disabled | Whether disabled | boolean | false |
| min | Minimum number of checkable items | number | — |
| max | Maximum number of checkable items | number | — |
| text-color | Active text color | string | — |
| fill | Active fill and border color | string | — |
| tag | Custom element tag | string | Component | 'div' |
CheckboxGroup Events
| Event Name | Description | Parameters |
|---|---|---|
| change | Triggered when binding value changes | (value: Array<string | number | boolean>) => void |
CheckboxGroup Slots
| Slot Name | Description |
|---|---|
| default | Custom default content |
Theme Variables
The Checkbox component uses the following CSS variables for style customization:
| Variable | Description | Default |
|---|---|---|
--yh-checkbox-font-size | Font size | var(--yh-font-size-base) |
--yh-checkbox-text-color | Text color | var(--yh-text-color-regular) |
--yh-checkbox-input-size | Checkbox size | 14px |
--yh-checkbox-input-border-color | Border color | var(--yh-border-color) |
--yh-checkbox-input-bg-color | Background color | var(--yh-fill-color-blank) |
--yh-checkbox-checked-bg-color | Checked background | var(--yh-color-primary) |
--yh-checkbox-checked-border-color | Checked border | var(--yh-color-primary) |
--yh-checkbox-checked-icon-color | Checked icon color | var(--yh-fill-color-blank) |
--yh-checkbox-disabled-bg-color | Disabled background | var(--yh-fill-color-light) |
--yh-checkbox-disabled-text-color | Disabled text color | var(--yh-text-color-placeholder) |