Switch

A toggle switch component with label, hint, and validation.

vu-switch · @velkin/react/switch

Copy page

Import

React

npm i @velkin/react

import { VuSwitch } from "@velkin/react/switch";

Examples

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Value restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks toggle (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change checked state (`readonly` attr).
required	`boolean`	—	Blocks valid submit when unchecked (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id forwarded to the internal input.
value	`string`	""	Form submit token when checked (`value` attr).
color	VuSwitchColor	"primary"	Intent palette token for the checked accent. Default: `"primary"`.
tone	VuSwitchTone	"normal"	Neutral idle-track weight (`subtle`/`normal`/`strong`). Default: `"normal"`.
size	VuSwitchSize	"md"	Track, gap, and label scale. Default: `"md"`.
variant	VuSwitchVariant	"default"	Track paint recipe. Default: `"default"`.
arialabel	`string`	—	Accessible name when no visible label.
compact	`boolean`	false	Tighter hint/error spacing (`compact` attr). Default: `false`.
defaultchecked	`boolean`	—	Restored by `reset()` / form reset (`defaultchecked` attr). Default: `false`.
showerrors	`boolean`	—	Shows validation after first blur when `required` (`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`.
checked	`boolean`	—	Checked state (`checked` attr). Default: `false`.
ariaLabel	`string`	""	Inner input accessible name when no string or slotted label (icon-only).
defaultChecked	`boolean`	false	Target checked state for `reset()` and `<form>.reset()`; reflects as `defaultchecked`.
showErrors	`boolean`	false	When true with `required`, shows `requiredMessage` after first blur if unchecked; reflects as `showerrors`.
validationActive	`boolean`	false	After first blur with `showerrors`, drives invalid styling and error text.

Events

Event	Detail	Description
vu-change	VuSwitchChangeDetail	User toggle; `detail.checked` boolean; `detail.value` submit token or boolean.
vu-invalid	VuSwitchValidationErrorDetail	When validation messages are recomputed while `validationActive`.
vu-clear	VuSwitchValueClearedDetail	After `reset()` syncs state from `defaultChecked`.

Slots

Slot	Description
label	Rich label markup; 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.

CSS parts

Part	Description
field	Column that stacks the control row, optional hint, and optional error.
wrapper	Row wrapper around the input and label.
input	The native checkbox input used as the switch control (`role="switch"`).
label	The label element for the switch row.
track	The rounded track behind the thumb.
thumb	The sliding thumb on the track.
hint	Neutral helper text under the label (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.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
check	- Sets checked to true.
uncheck	- Sets checked to false.
toggle	- Flips checked state.
validateInput	- Runs `required` validation; `vu-form` calls this when aggregating field errors.
reset	- Resets to `defaultChecked`, clears validation UI, and dispatches `vu-clear`.

Types

Name	Definition
VuSwitchChangeDetail	`{ checked: boolean; value: string \| boolean \| undefined; }`
VuSwitchColor	`"default" \| "primary" \| "success" \| "warning" \| "danger"`
VuSwitchSize	`"sm" \| "md" \| "lg"`
VuSwitchTone	`"subtle" \| "normal" \| "strong"`
VuSwitchValidationErrorDetail	`{ errors: string[]; }`
VuSwitchValueClearedDetail	`{ value: string; checked: boolean; }`
VuSwitchVariant	`"outline" \| "default" \| "soft"`

Import

React

API

Props

Prop	Type	Default	Description
name	`string`	—	Form field name for submit (`name` attr).
defaultvalue	`string`	—	Value restored on `<form reset>` (`defaultvalue` attr).
formid	`string`	—	External `<form>` id (`formid` attr).
disabled	`boolean`	—	Non-interactive; blocks toggle (`disabled` attr).
readonly	`boolean`	—	Focusable but cannot change checked state (`readonly` attr).
required	`boolean`	—	Blocks valid submit when unchecked (`required` attr).
requiredmessage	`string`	—	Custom `valueMissing` message (`requiredmessage` attr).
label	`string`	""	Plain-text label; slotted `label` wins when assigned.
hint	`string`	""	Helper text; `hint` slot wins when assigned.
id	`string`	""	Host id forwarded to the internal input.
value	`string`	""	Form submit token when checked (`value` attr).
color	VuSwitchColor	"primary"	Intent palette token for the checked accent. Default: `"primary"`.
tone	VuSwitchTone	"normal"	Neutral idle-track weight (`subtle`/`normal`/`strong`). Default: `"normal"`.
size	VuSwitchSize	"md"	Track, gap, and label scale. Default: `"md"`.
variant	VuSwitchVariant	"default"	Track paint recipe. Default: `"default"`.
arialabel	`string`	—	Accessible name when no visible label.
compact	`boolean`	false	Tighter hint/error spacing (`compact` attr). Default: `false`.
defaultchecked	`boolean`	—	Restored by `reset()` / form reset (`defaultchecked` attr). Default: `false`.
showerrors	`boolean`	—	Shows validation after first blur when `required` (`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`.
checked	`boolean`	—	Checked state (`checked` attr). Default: `false`.
ariaLabel	`string`	""	Inner input accessible name when no string or slotted label (icon-only).
defaultChecked	`boolean`	false	Target checked state for `reset()` and `<form>.reset()`; reflects as `defaultchecked`.
showErrors	`boolean`	false	When true with `required`, shows `requiredMessage` after first blur if unchecked; reflects as `showerrors`.
validationActive	`boolean`	false	After first blur with `showerrors`, drives invalid styling and error text.

Events

Event	Detail	Description
vu-change	VuSwitchChangeDetail	User toggle; `detail.checked` boolean; `detail.value` submit token or boolean.
vu-invalid	VuSwitchValidationErrorDetail	When validation messages are recomputed while `validationActive`.
vu-clear	VuSwitchValueClearedDetail	After `reset()` syncs state from `defaultChecked`.

Slots

Slot	Description
label	Rich label markup; 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.

CSS parts

Part	Description
field	Column that stacks the control row, optional hint, and optional error.
wrapper	Row wrapper around the input and label.
input	The native checkbox input used as the switch control (`role="switch"`).
label	The label element for the switch row.
track	The rounded track behind the thumb.
thumb	The sliding thumb on the track.
hint	Neutral helper text under the label (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.
text	String `label` text when the `label` slot is empty.

Methods

Method	Description
check	- Sets checked to true.
uncheck	- Sets checked to false.
toggle	- Flips checked state.
validateInput	- Runs `required` validation; `vu-form` calls this when aggregating field errors.
reset	- Resets to `defaultChecked`, clears validation UI, and dispatches `vu-clear`.

Types

Name	Definition
VuSwitchChangeDetail	`{ checked: boolean; value: string \| boolean \| undefined; }`
VuSwitchColor	`"default" \| "primary" \| "success" \| "warning" \| "danger"`
VuSwitchSize	`"sm" \| "md" \| "lg"`
VuSwitchTone	`"subtle" \| "normal" \| "strong"`
VuSwitchValidationErrorDetail	`{ errors: string[]; }`
VuSwitchValueClearedDetail	`{ value: string; checked: boolean; }`
VuSwitchVariant	`"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