Checkbox Group

A checkbox group component with shared label and validation.

vu-checkbox-group · @velkin/react/checkbox-group

Copy page

Import

React

npm i @velkin/react

import { VuCheckboxGroup } from "@velkin/react/checkbox-group";

Examples

API

Props

Prop	Type	Default	Description
orientation	VuCheckboxGroupOrientation	"vertical"	`vertical` (default) stacks members; `horizontal` wraps them in a row.
legend	`string`	""	Plain-text in-group caption (muted vs string label); use slot="legend" for markup.
label	`string`	""	Plain-text field label above the group; use slot="label" for markup.
hint	`string`	""	Plain-text helper under the group; use `slot="hint"` for markup.
ariaLabel	`string`	""	Accessible name when there is no visible label or legend.
variant	VuCheckboxVariant	"default"	Forwarded to members that omit their own `variant`.
color	VuCheckboxColor	"primary"	Forwarded to members that omit their own `color`.
tone	VuCheckboxTone	"normal"	Forwarded to members that omit their own `tone`.
size	VuCheckboxSize	"md"	Forwarded to members that omit their own `size`.
radius	VuCheckboxGroupRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
name	`string`	—	Form field name forwarded to every member. Default: `""`.
defaultvalue	`string`	—	JSON array restored on `<form reset>` (`defaultvalue` attr).
formid	`string \| null`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	false	Disables every member while set (releases only attrs this group claimed).
readonly	`boolean`	false	Forwarded to members; blocks interaction (inherited from `FormControlBase`).
required	`boolean`	false	When true, `checkValidity` / `reportValidity` fail until at least one member is checked.
requiredMessage	`string`	"This field is required."	Message for host `valueMissing` when `required` and nothing is selected.
compact	`boolean`	false	Tighter hint and error spacing.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
values	`undefined \| string[]`	undefined	Selected member `value` tokens (`on` for empty member `value`); when set from JS, syncs member `checked`. Omit for uncontrolled usage.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuCheckboxGroupChangeDetail	After a member toggles; `detail.values` mirrors `values` when controlled. Fired on the group host (not the member).
vu-invalid	VuCheckboxGroupValidationErrorDetail	When validation messages are recomputed while `validationActive`.

Slots

Slot	Description
—	- One or more `<vu-checkbox>` members (other nodes are ignored for forwarding).
label	Rich field label; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
legend	Rich legend inside the group; takes precedence over string `legend` when assigned.

CSS parts

Part	Description
field	Column that stacks label, group, hint, and error.
label	Field label wrapper (string `label` or `label` slot).
text	String `label` when the `label` slot is empty.
base	`role="group"` wrapper (legend + default slot).
legend	In-group caption row; styled quieter than part label.
fields	Flex container around checkboxes.
hint	Helper text region (string `hint` or `hint` slot).
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.

Methods

Method	Description
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
string[] \| undefined	`undefined \| string[]`
VuCheckboxColor	`"default" \| "primary" \| "success" \| "warning" \| "danger"`
VuCheckboxGroupChangeDetail	`{ values: string[]; source: HTMLElement \| null; }`
VuCheckboxGroupOrientation	`"horizontal" \| "vertical"`
VuCheckboxGroupRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuCheckboxGroupValidationErrorDetail	`{ errors: string[]; }`
VuCheckboxSize	`"sm" \| "md" \| "lg"`
VuCheckboxTone	`"subtle" \| "normal" \| "strong"`
VuCheckboxVariant	`"outline" \| "default" \| "soft"`

Import

React

API

Props

Prop	Type	Default	Description
orientation	VuCheckboxGroupOrientation	"vertical"	`vertical` (default) stacks members; `horizontal` wraps them in a row.
legend	`string`	""	Plain-text in-group caption (muted vs string label); use slot="legend" for markup.
label	`string`	""	Plain-text field label above the group; use slot="label" for markup.
hint	`string`	""	Plain-text helper under the group; use `slot="hint"` for markup.
ariaLabel	`string`	""	Accessible name when there is no visible label or legend.
variant	VuCheckboxVariant	"default"	Forwarded to members that omit their own `variant`.
color	VuCheckboxColor	"primary"	Forwarded to members that omit their own `color`.
tone	VuCheckboxTone	"normal"	Forwarded to members that omit their own `tone`.
size	VuCheckboxSize	"md"	Forwarded to members that omit their own `size`.
radius	VuCheckboxGroupRadius	"md"	Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`.
name	`string`	—	Form field name forwarded to every member. Default: `""`.
defaultvalue	`string`	—	JSON array restored on `<form reset>` (`defaultvalue` attr).
formid	`string \| null`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	false	Disables every member while set (releases only attrs this group claimed).
readonly	`boolean`	false	Forwarded to members; blocks interaction (inherited from `FormControlBase`).
required	`boolean`	false	When true, `checkValidity` / `reportValidity` fail until at least one member is checked.
requiredMessage	`string`	"This field is required."	Message for host `valueMissing` when `required` and nothing is selected.
compact	`boolean`	false	Tighter hint and error spacing.
showerrors	`boolean`	—	Shows validation after activation (`showerrors` attr). Default: `false`.
validationactive	`boolean`	—	Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalid	`boolean`	false	True when last validation found errors (`invalid` attr). Default: `false`.
values	`undefined \| string[]`	undefined	Selected member `value` tokens (`on` for empty member `value`); when set from JS, syncs member `checked`. Omit for uncontrolled usage.
showErrors	`boolean`	false	Shows validation after activation.
validationActive	`boolean`	false	Drives invalid styling after activation.

Events

Event	Detail	Description
vu-change	VuCheckboxGroupChangeDetail	After a member toggles; `detail.values` mirrors `values` when controlled. Fired on the group host (not the member).
vu-invalid	VuCheckboxGroupValidationErrorDetail	When validation messages are recomputed while `validationActive`.

Slots

Slot	Description
—	- One or more `<vu-checkbox>` members (other nodes are ignored for forwarding).
label	Rich field label; takes precedence over string `label` when assigned.
hint	Optional helper copy (HTML); overrides string `hint` when assigned.
error	Replaces default validation message list when assigned.
legend	Rich legend inside the group; takes precedence over string `legend` when assigned.

CSS parts

Part	Description
field	Column that stacks label, group, hint, and error.
label	Field label wrapper (string `label` or `label` slot).
text	String `label` when the `label` slot is empty.
base	`role="group"` wrapper (legend + default slot).
legend	In-group caption row; styled quieter than part label.
fields	Flex container around checkboxes.
hint	Helper text region (string `hint` or `hint` slot).
error-message	Region for `slot="error"` or stacked default validation lines.
error-line	One default validation string when `slot="error"` is empty.

Methods

Method	Description
validateInput	- Runs validators and syncs validity.

Types

Name	Definition
string[] \| undefined	`undefined \| string[]`
VuCheckboxColor	`"default" \| "primary" \| "success" \| "warning" \| "danger"`
VuCheckboxGroupChangeDetail	`{ values: string[]; source: HTMLElement \| null; }`
VuCheckboxGroupOrientation	`"horizontal" \| "vertical"`
VuCheckboxGroupRadius	`"sm" \| "md" \| "lg" \| "none" \| "full"`
VuCheckboxGroupValidationErrorDetail	`{ errors: string[]; }`
VuCheckboxSize	`"sm" \| "md" \| "lg"`
VuCheckboxTone	`"subtle" \| "normal" \| "strong"`
VuCheckboxVariant	`"outline" \| "default" \| "soft"`

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse

Import

Examples

API

Props

Events

Slots

CSS parts

Methods

Types

Related

Inputs

Guides

Browse