Skip to content
Velkin LogoVelkin Logo
Velkin
VELKIN/UI

Modern UI components for product teams and their AI agents. Lit core, typed wrappers, live MCP.

sales@velkinui.com

Product

  • Docs
  • Components
  • Studio
  • Pricing

Resources

  • Quick start
  • Blog
  • Changelog
  • Roadmap
  • Status

Project

  • About
  • Contact
  • License
  • Privacy
  • Terms

© 2026 Velkin. MIT core · Pro licenses available.

VELKIN

Checkbox

A checkbox component with label, hint, and validation.

vu-checkbox · @velkin/react/checkbox

Copy page

Import

React
npm i @velkin/react

import { VuCheckbox } from "@velkin/react/checkbox";

Examples

API

Props

PropTypeDefaultDescription
namestring—Form field name for submit (`name` attr).
defaultvaluestring—Value restored on `<form reset>` (`defaultvalue` attr).
formidstring—External `<form>` id (`formid` attr).
disabledboolean—Non-interactive; blocks toggle (`disabled` attr).
readonlyboolean—Focusable but cannot change checked state (`readonly` attr).
requiredboolean—Blocks valid submit when unchecked (`required` attr).
requiredmessagestring—Custom `valueMissing` message (`requiredmessage` attr).
labelstring""Plain-text label; slotted `label` wins when assigned.
hintstring""Helper text; `hint` slot wins when assigned.
idstring""Host id forwarded to the internal input.
valuestring""Form submit token when checked (`value` attr).
colorVuCheckboxColor"primary"Intent palette token for the checked accent. Default: `"primary"`.
toneVuCheckboxTone"normal"Neutral idle-box weight (`subtle`/`normal`/`strong`). Default: `"normal"`.
sizeVuCheckboxSize"md"Box, gap, and label scale (`sm`/`md`/`lg`). Default: `"md"`.
radiusVuCheckboxRadius"md"Corner preset (`none`/`sm`/`md`/`lg`/`full`). Default: `md`. Uses `--vu-radius-*` (not control-radius) so the small box stays square-ish.
variantVuCheckboxVariant"default"Box paint recipe. Default: `"default"`.
indeterminateclickVuCheckboxIndeterminateClick—First click from indeterminate (`indeterminateclick` attr). Default: `"check"`.
arialabelstring—Accessible name when no visible label.
compactbooleanfalseTighter hint/error spacing (`compact` attr). Default: `false`.
defaultcheckedboolean—Restored by `reset()` / form reset (`defaultchecked` attr). Default: `false`.
showerrorsboolean—Shows validation after first blur when `required` (`showerrors` attr). Default: `false`.
validationactiveboolean—Drives invalid styling after activation (`validationactive` attr). Default: `false`.
invalidbooleanfalseTrue when last validation found errors (`invalid` attr). Default: `false`.
checkedboolean—Checked state (`checked` attr). Default: `false`.
indeterminateboolean—Mixed/indeterminate state (`indeterminate` attr). Default: `false`.
indeterminateClickVuCheckboxIndeterminateClick"check"First click from `indeterminate`: `check` (native) or `uncheck`.
ariaLabelstring""Inner input accessible name when no string or slotted label (icon-only).
defaultCheckedbooleanfalseTarget checked state for `reset()` and `<form>.reset()`; reflects as `defaultchecked`.
showErrorsbooleanfalseWhen true with `required`, shows `requiredMessage` after first blur if unchecked; reflects as `showerrors`.
validationActivebooleanfalseAfter first blur with `showerrors`, drives invalid styling and error text.

Events

EventDetailDescription
vu-changeVuCheckboxChangeDetailUser toggle; `detail.checked` boolean; `detail.value` submit token or boolean.
vu-invalidVuCheckboxValidationErrorDetailWhen validation messages are recomputed while `validationActive`.
vu-clearVuCheckboxValueClearedDetailAfter `reset()` syncs state from `defaultChecked`.

Slots

SlotDescription
labelRich label markup; takes precedence over string `label` when assigned.
hintOptional helper copy (HTML); overrides string `hint` when assigned.
errorReplaces default validation message list when assigned.

CSS parts

PartDescription
fieldColumn that stacks the control row, optional hint, and optional error.
wrapperThe wrapper element for the checkbox.
inputThe native input element used for the checkbox.
labelThe label element for the checkbox, used for styling.
boxThe visual box for the checkbox, which includes the checkmark and indeterminate state.
checkmarkThe checkmark icon that appears when the checkbox is checked.
indeterminate-lineThe line representing the indeterminate state of the checkbox.
hintNeutral helper text under the label (string `hint` or `hint` slot).
error-messageRegion for `slot="error"` or stacked default validation lines.
error-lineOne default validation string when `slot="error"` is empty.
textString `label` text when the `label` slot is empty.

Types

NameDefinition
VuCheckboxChangeDetail
{
  checked: boolean;
  value: string | boolean | undefined;
}
VuCheckboxColor
"default" | "primary" | "success" | "warning" | "danger"
VuCheckboxIndeterminateClick
"check" | "uncheck"
VuCheckboxRadius
"sm" | "md" | "lg" | "none" | "full"
VuCheckboxSize
"sm" | "md" | "lg"
VuCheckboxTone
"subtle" | "normal" | "strong"
VuCheckboxValidationErrorDetail
{ errors: string[]; }
VuCheckboxValueClearedDetail
{ value: string; checked: boolean; }
VuCheckboxVariant
"outline" | "default" | "soft"

Related

Inputs

  • Advanced FilterAn advanced filter component with expression input and visual builder.
  • ButtonA clickable button component with multiple variants and states.
  • Button GroupA button group component with shared styling and optional selection.
  • Checkbox GroupA checkbox group component with shared label and validation.
  • Color AreaA two-dimensional color picker component for saturation and brightness.
  • Color PickerA color picker component with swatches, sliders, and input field.

Guides

  • FormsFormData, VuForm, and validation
  • EventsonVu* / v-model / e.detail
  • Appearancevariant, color, tone, size

Browse

  • Previous: Button GroupEarlier in the sidebar
  • Next: Checkbox GroupLater in the sidebar
  • All componentsBrowse the full index