Component detail entry

Forms

@vean/ui

SCheckbox

Checkbox

Checkbox belongs to the Forms category. Start with demos and usage, then use the API tables to finish integration and styling decisions.

Use the quick jump panel to reach overview, usage, demos, and API first, then continue through the full page.

Quick jump

Overview Usage Demos API Changelog

Related components

If you are composing interactions in the same family, these components usually pair well together.

Autocomplete Calendar ColorArea ColorField ColorPicker ColorSlider

Checkbox

Overview

A control that lets the user select or clear an option, with an indeterminate half-check state for partial selections. It ships as a standalone control, a roving-focus group, and data-driven card variants. Use it for independent toggles, multi-select lists, and “select all” scenarios with cascading half-check; for single-choice from a set, prefer SRadioGroup.

Usage

Features

☑️ Tri-state model — CheckedState of boolean | 'indeterminate', reflected via both aria-checked (mixed) and data-state
🗂 Groups with roving-focus keyboard navigation (useRovingFocusGroup, Arrow keys)
🏷 Accessible label — SCheckboxLabel wires for to the control’s id
📋 Native form proxy — renders a visually hidden input carrying name / value (default 'on') / checked for form submission
🃏 Card variants (SCheckboxCard / SCheckboxCardGroup) with icon, label, and description content
🎨 6 sizes, 8 colors, 2 shapes, and horizontal/vertical orientation via checkboxVariants
📊 Data-driven Compact aggregation — CheckboxGroupCompact / CheckboxCardGroupCompact own iteration and default composition
♿ role="checkbox" with full aria support, axe-clean across all four forms

Component family

SCheckbox - base checkbox with label, control, and indicator
SCheckboxGroup - vertical/horizontal group with roving-focus navigation and form proxy
SCheckboxCard - card checkbox with icon, label, and description
SCheckboxCardGroup - data-driven group of card checkboxes

Demos

Basic

100%

Checkbox

Icon

100%

Rounded

Group

100%

Check All

Apple

Orange

Banana

Grape

Card

100%

Label

this is a description

Card Group

100%

Check All

Apple

Orange

Banana

Grape

API

Aria Layer

Checkbox

16 Props1 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	the class of root element
ui	Partial<CheckboxUi>	—	Per-slot class overrides for the component.
color	ThemeColor	—	Theme color of the component.
size	ThemeSize	—	Visual size of the component.
shape	CheckboxShape	—	Shape of the component.
label	string	—	Label text rendered by the component.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
id	string	—	Id.
modelValue	CheckedState \| null	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	CheckedState	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
value	DefinedValue	on	The value given as data when submitted with a `name`.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkbox
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	CheckedState \| null	Event handler called when the value of the checkbox changes.

CheckboxCard

18 Props1 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	the class of root element
ui	Partial<CheckboxCardUi>	—	Per-slot class overrides for the component.
color	ThemeColor	—	Theme color of the component.
size	ThemeSize	—	Visual size of the component.
shape	CheckboxShape	—	Shape of the component.
icon	string	—	Icon rendered by the component.
description	string	—	Description text rendered by the component.
label	string	—	Label text rendered by the component.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
id	string	—	Id.
modelValue	CheckedState \| null	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	CheckedState	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
value	DefinedValue	on	The value given as data when submitted with a `name`.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkbox
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	CheckedState \| null	Event handler called when the value of the checkbox changes.

CheckboxCardCompact

13 Props1 Emits

Props

Prop	Type	Default	Description
icon	IconValue	—	Icon rendered by the component.
description	string	—	Description text rendered by the component.
label	string	—	Label text rendered by the component.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
id	string	—	Id.
modelValue	CheckedState \| null	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	CheckedState	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
value	DefinedValue	on	The value given as data when submitted with a `name`.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkbox
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	CheckedState \| null	Event handler called when the value of the checkbox changes.

CheckboxCardGroup<T>

19 Props1 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	the class of group root element
ui	Partial<CheckboxCardUi>	—	Per-slot class overrides for the component.
color	ThemeColor	—	Theme color of the component.
size	ThemeSize	—	Visual size of the component.
shape	CheckboxShape	—	Shape of the component.
items	T[]	—	Items rendered by the component.
rootProps	CheckboxRootProps	—	Properties forwarded to the root element.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
modelValue	T['value'][]	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	T['value'][]	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
rovingFocus	boolean	true	When `false`, navigating through the items using arrow keys will be disabled.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkboxes
dir	Direction	—	The direction of navigation between items.
loop	boolean	false	Whether keyboard navigation should loop around
orientation	DataOrientation	—	The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	T[]	Event handler called when the value of the checkbox group changes.

CheckboxCardGroupCompact<T>

14 Props1 Emits

Props

Prop	Type	Default	Description
items	T[]	—	Items rendered by the component.
rootProps	CheckboxRootProps	—	Properties forwarded to the root element.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
modelValue	T['value'][]	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	T['value'][]	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
rovingFocus	boolean	true	When `false`, navigating through the items using arrow keys will be disabled.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkboxes
dir	Direction	—	The direction of navigation between items.
loop	boolean	false	Whether keyboard navigation should loop around
orientation	DataOrientation	—	The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	T[]	Event handler called when the value of the checkbox group changes.

CheckboxCompact

11 Props1 Emits

Props

Prop	Type	Default	Description
label	string	—	Label text rendered by the component.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
id	string	—	Id.
modelValue	CheckedState \| null	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	CheckedState	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
value	DefinedValue	on	The value given as data when submitted with a `name`.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkbox
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	CheckedState \| null	Event handler called when the value of the checkbox changes.

CheckboxControl

5 Props

Props

Prop	Type	Default	Description
id	string	—	Id of the element
type	ButtonType	'button'	The type of the button element. Can be one of 'button', 'submit', or 'reset'.
disabled	boolean	—	Whether the component is disabled.
asChild	boolean	—	Change the default rendered element for the one passed as a child, merging their props and behavior.
as	AsTag \| Component	'div'	The element or component this component should render as. Can be overwrite by `asChild`

CheckboxGroup<T>

19 Props1 Emits

Props

Prop	Type	Default	Description
class	ClassValue	—	the class of group root element
ui	Partial<CheckboxUi>	—	Per-slot class overrides for the component.
color	ThemeColor	—	Theme color of the component.
size	ThemeSize	—	Visual size of the component.
shape	CheckboxShape	—	Shape of the component.
items	T[]	—	Items rendered by the component.
rootProps	CheckboxRootProps	—	Properties forwarded to the root element.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
modelValue	T['value'][]	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	T['value'][]	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
rovingFocus	boolean	true	When `false`, navigating through the items using arrow keys will be disabled.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkboxes
dir	Direction	—	The direction of navigation between items.
loop	boolean	false	Whether keyboard navigation should loop around
orientation	DataOrientation	—	The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	T[]	Event handler called when the value of the checkbox group changes.

CheckboxGroupCompact<T>

14 Props1 Emits

Props

Prop	Type	Default	Description
items	T[]	—	Items rendered by the component.
rootProps	CheckboxRootProps	—	Properties forwarded to the root element.
controlProps	CheckboxControlProps	—	Properties forwarded to the control element.
indicatorProps	CheckboxIndicatorProps	—	Properties forwarded to the indicator element.
labelProps	LabelProps	—	Properties forwarded to the label element.
modelValue	T['value'][]	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	T['value'][]	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
rovingFocus	boolean	true	When `false`, navigating through the items using arrow keys will be disabled.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkboxes
dir	Direction	—	The direction of navigation between items.
loop	boolean	false	Whether keyboard navigation should loop around
orientation	DataOrientation	—	The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	T[]	Event handler called when the value of the checkbox group changes.

CheckboxGroupRoot<T>

9 Props1 Emits

Props

Prop	Type	Default	Description
modelValue	T[]	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	T[]	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
rovingFocus	boolean	true	When `false`, navigating through the items using arrow keys will be disabled.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkboxes
dir	Direction	—	The direction of navigation between items.
loop	boolean	false	Whether keyboard navigation should loop around
orientation	DataOrientation	—	The orientation of the group. Mainly so arrow navigation is done accordingly (left & right vs. up & down)
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	T[]	Event handler called when the value of the checkbox group changes.

CheckboxIndicator

3 Props

Props

Prop	Type	Default	Description
forceMount	boolean	—	Used to force mounting when more control is needed. Useful when controlling animation with Vue animation libraries.
asChild	boolean	—	Change the default rendered element for the one passed as a child, merging their props and behavior.
as	AsTag \| Component	'div'	The element or component this component should render as. Can be overwrite by `asChild`

CheckboxLabel

CheckboxRoot

7 Props1 Emits

Props

Prop	Type	Default	Description
id	string	—	Id.
modelValue	CheckedState \| null	—	The controlled value of the checkbox. Can be bound with v-model.
defaultValue	CheckedState	—	The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
value	DefinedValue	on	The value given as data when submitted with a `name`.
disabled	boolean	false	When `true`, prevents the user from interacting with the checkbox
name	string	—	The name of the field. Submitted with its owning form as part of a name/value pair.
required	boolean	—	When `true`, indicates that the user must set the value before the owning form can be submitted.

Emits

Emit Name	Parameters	Description
update:modelValue	CheckedState \| null	Event handler called when the value of the checkbox changes.

Notes

Architecture and benchmark differences

VeanUI builds checkbox with a single-source tri-state state machine: CheckboxRoot (useControllableState + CheckedState) derives ariaChecked (indeterminate → mixed) and dataState (checked / indeterminate / unchecked), which CheckboxControl reflects on role="checkbox" while CheckboxIndicator mounts conditionally via usePresence. Group value changes are emitted by CheckboxGroupRoot, which wraps useRovingFocusGroup for arrow-key navigation and renders a VisuallyHiddenInput form proxy. The scv() recipes checkboxVariants / checkboxCardVariants declare 6 sizes, 8 colors, and 2 shapes; all four Compact layers own iteration and default composition while the UI wrappers only inject variant classes.

Capability	VeanUI	Ant Design `Checkbox`	Element Plus `Checkbox`	Mantine `Checkbox`	shadcn/ui `Checkbox`
Aria/styled split	✅	—	—	—	✅
Tri-state (indeterminate)	✅	✅	✅	✅	✅
Independent `indeterminate` prop	➕	✅	✅	✅	—
Form value mapping	✅	✅	✅	✅	✅
Card variant (icon/description)	✅	—	—	—	—
Group roving-focus keyboard nav	✅	✅	✅	✅	—
`button` variant	➕	✅	✅	—	—
Select-all / half-check helper	➕	✅	—	—	—

Cautions

The half-check state is driven by modelValue="indeterminate"; a dedicated indeterminate prop is a roadmap enhancement, not yet implemented.
A disabled group disables every item; an individual disabled on an item is honored inside an enabled group.
The form proxy activates when a name is present — pair it with a native <form> or the SForm integration to submit values.
The indicator uses pointer-events: none so clicks always land on the control itself.

FAQ

How do I show a partial / indeterminate state?

Pass modelValue="indeterminate" (or defaultValue); the control reflects aria-checked="mixed" and data-state="indeterminate".

How do I build a “select all” list?

Combine a master SCheckbox with modelValue="indeterminate" and an SCheckboxGroup; mirror the group’s update:modelValue back to the master to drive the half-check.

How do I submit checkbox values with a form?

Give the checkbox or group a name; the component renders a visually hidden input so native form submission carries value (default 'on') or the array of checked values.

What is the difference between `SCheckboxCard` and `SCheckbox`?

SCheckboxCard renders a bordered card with icon / label / description content slots and a data-[state=checked] border highlight; SCheckbox is the bare control.

Changelog

Version history is grouped by release so you can quickly see what changed for this component across published versions.

v0.19.0

2026-05-11

Compare release

Optimization

update component structure for improved readability

Scope: checkboxAuthors: soybeanfeView commit3a6a2

Optimization

set default rovingFocus prop in CheckboxCardGroupCompact

Scope: checkboxAuthors: soybeanfeView commit5930e

Optimization

set default rovingFocus prop in CheckboxCardGroup and CheckboxGroup

Scope: checkboxAuthors: soybeanfeView commitd659e

v0.15.0

2026-04-26

Compare release

Fix

update forwardedProps to omit 'class' instead of 'label'

Scope: checkboxAuthors: soybeanfeView commit0d537

Docs

fix emit parameter syntax for consistency

Scope: checkboxAuthors: soybeanjs, CopilotView commit1d2d7

Fix

update forwardedProps to omit 'class' instead of 'label'

Scope: checkboxAuthors: soybeanfeView commit0d537

v0.9.0

2026-03-01

Compare release

Fix

conditionally render CheckboxLabel based on slot or label presence; update root variant style

Scope: checkboxAuthors: soybeanjsView commit78f2b

v0.0.20

2026-01-21

Compare release

Docs

fix markdown format

Scope: checkboxAuthors: soybeanjsView commit762c9

v0.0.19

2026-01-19

Compare release

Feature

support enter keyboard to toggle checked state

Scope: checkboxAuthors: soybeanjsView commit75ddd

v0.0.2

2025-11-18

Compare release

Feature

add Checkbox component with various states and group functionality

Scope: checkboxAuthors: soybeanjsView commit3dfcb

Feature

refactor checkbox components to utilize new theme context and improve structure with SCheckbox and SCheckboxGroup

Scope: checkboxAuthors: soybeanjsView commit81075

Feature

add CheckboxCard and CheckboxCardGroup components, enhancing checkbox functionality with card layouts and improved UI integration

Scope: checkboxAuthors: soybeanjsView commit1b764

Feature

add color and size examples, enhance checkbox card and group components with color support, and improve checkbox labels

Scope: checkboxAuthors: soybeanjsView commitac32d

Feature

introduce shape and icon examples, enhance checkbox components with shape support, and update card group styling

Scope: checkboxAuthors: soybeanjsView commitbbd07

Fix

update click handler to check for groupContext existence before accessing modelValue

Scope: checkboxAuthors: soybeanjsView commit78fda

Refactor

remove unused constants and CSS variables from shared checkbox file

Scope: checkboxAuthors: soybeanjsView commit494f4

Refactor

consolidate CheckedState type definition and update related functions for clarity

Scope: checkboxAuthors: soybeanjsView commitfac63

Refactor

simplify checkbox component structure and enhance group functionality with improved state management

Scope: checkboxAuthors: soybeanjsView commit4d4ec

Refactor

enhance accessibility and state management by introducing getAriaLabel function and updating element references

Scope: checkboxAuthors: soybeanjsView commit472ba

Refactor

improve type safety by ensuring modelValue updates only with non-nullable values

Scope: checkboxAuthors: soybeanjsView commit1c300

Refactor

update checkbox context and styling to use data-state attribute for improved state management

Scope: checkboxAuthors: soybeanjsView commitca1b5

Refactor

move isIndeterminate function to shared utility and clean up imports

Scope: checkboxAuthors: soybeanjsView commit61449

Feature

add Checkbox component with various states and group functionality

Scope: checkboxAuthors: soybeanjsView commit3dfcb

Feature

refactor checkbox components to utilize new theme context and improve structure with SCheckbox and SCheckboxGroup

Scope: checkboxAuthors: soybeanjsView commit81075

Feature

add CheckboxCard and CheckboxCardGroup components, enhancing checkbox functionality with card layouts and improved UI integration

Scope: checkboxAuthors: soybeanjsView commit1b764

Feature

add color and size examples, enhance checkbox card and group components with color support, and improve checkbox labels

Scope: checkboxAuthors: soybeanjsView commitac32d

Feature

introduce shape and icon examples, enhance checkbox components with shape support, and update card group styling

Scope: checkboxAuthors: soybeanjsView commitbbd07

Fix

update click handler to check for groupContext existence before accessing modelValue

Scope: checkboxAuthors: soybeanjsView commit78fda

Refactor

remove unused constants and CSS variables from shared checkbox file

Scope: checkboxAuthors: soybeanjsView commit494f4

Refactor

consolidate CheckedState type definition and update related functions for clarity

Scope: checkboxAuthors: soybeanjsView commitfac63

Refactor

simplify checkbox component structure and enhance group functionality with improved state management

Scope: checkboxAuthors: soybeanjsView commit4d4ec

Refactor

enhance accessibility and state management by introducing getAriaLabel function and updating element references

Scope: checkboxAuthors: soybeanjsView commit472ba

Refactor

improve type safety by ensuring modelValue updates only with non-nullable values

Scope: checkboxAuthors: soybeanjsView commit1c300

Refactor

update checkbox context and styling to use data-state attribute for improved state management

Scope: checkboxAuthors: soybeanjsView commitca1b5

Refactor

move isIndeterminate function to shared utility and clean up imports

Scope: checkboxAuthors: soybeanjsView commit61449

Quick jump

Related components

Checkbox

Overview

Usage

Features

Component family

Demos

Basic

Icon

Group

Card

Card Group

API

Aria Layer

Checkbox

Props

Emits

CheckboxCard

Props

Emits

CheckboxCardCompact

Props

Emits

CheckboxCardGroup<T>

Props

Emits

CheckboxCardGroupCompact<T>

Props

Emits

CheckboxCompact

Props

Emits

CheckboxControl

Props

CheckboxGroup<T>

Props

Emits

CheckboxGroupCompact<T>

Props

Emits

CheckboxGroupRoot<T>

Props

Emits

CheckboxIndicator

Props

CheckboxLabel

CheckboxRoot

Props

Emits

Notes

Architecture and benchmark differences

Cautions

FAQ

How do I show a partial / indeterminate state?

How do I build a “select all” list?

How do I submit checkbox values with a form?

What is the difference between SCheckboxCard and SCheckbox?

Changelog

v0.19.0

Optimization

Optimization

Optimization

v0.15.0

Fix

Docs

Fix

v0.9.0

Fix

v0.0.20

Docs

v0.0.19

Feature

v0.0.2

Feature

Feature

Feature

Feature

Feature

Fix

What is the difference between `SCheckboxCard` and `SCheckbox`?