Basic Components

Checkbox

Allows users to select one or more options from a set. Checkboxes are ideal for binary choices and multiple selections within forms.

Source Edit this page

Allows users to select one or more options from a set. Checkboxes are ideal for binary choices and multiple selections within forms.

When to Use

Boolean form fields (terms, opt-ins, feature toggles in settings).
Multi-select lists where each option is independent of the others.
"Select all" / batch actions inside tables or list pages.
Pair with a Label so the entire label area is clickable.

When NOT to Use

For mutually exclusive options — use a radio group.
For single on/off settings where a switch metaphor is clearer — a switch component is the better pattern.

Customizing

Set app-wide Checkbox defaults with ThemeProvider's themeDefaults and tune the checked-state visuals with extraClasses:

import { ThemeProvider, Checkbox } from '@vaneui/ui';

<ThemeProvider
  themeDefaults={{ checkbox: { input: { lg: true } } }}
  extraClasses={{ checkbox: { input: { primary: 'checked:bg-brand-600 checked:border-brand-600' } } }}
>
  <Checkbox>I agree to the terms</Checkbox>
</ThemeProvider>

Basic Usage

Checkbox should be used inside a Label with matching id/htmlFor.

I agree to the Terms of Service and Privacy Policy.

Receive product updates

Occasional emails about new features

<Col>
  <Label htmlFor="terms">
    <Checkbox id="terms"/>
    <span>I agree to the <Link href="#">Terms of Service</Link> and <Link href="#">Privacy Policy</Link>.</span>
  </Label>

  <Label htmlFor="emails">
    <Checkbox defaultChecked id="emails"/>
    <Col noGap tag="span">
      <Text>Receive product updates</Text>
      <Text xs secondary>Occasional emails about new features</Text>
    </Col>
  </Label>
</Col>

Sizes

Checkboxes in different sizes: xs, sm, md (default), lg, xl. A Checkbox nested inside a Label inherits the Label's size automatically — set it once on the Label and both scale together.

<Row flexWrap>
  <Label xs htmlFor="size-xs">
    <Checkbox id="size-xs" defaultChecked/>
    Size: xs
  </Label>
  <Label sm htmlFor="size-sm">
    <Checkbox id="size-sm" defaultChecked/>
    Size: sm
  </Label>
  <Label md htmlFor="size-md">
    <Checkbox id="size-md" defaultChecked/>
    Size: md
  </Label>
  <Label lg htmlFor="size-lg">
    <Checkbox id="size-lg" defaultChecked/>
    Size: lg
  </Label>
  <Label xl htmlFor="size-xl">
    <Checkbox id="size-xl" defaultChecked/>
    Size: xl
  </Label>
</Row>

Appearances

Different color appearances applied to the Checkbox; always place inside a Label.

<Row flexWrap>
  <Label htmlFor="appearance-primary">
    <Checkbox id="appearance-primary" defaultChecked/>
    Enable primary style
  </Label>
  <Label brand htmlFor="appearance-brand">
    <Checkbox brand id="appearance-brand" defaultChecked/>
    Enable brand style
  </Label>
  <Label accent htmlFor="appearance-accent">
    <Checkbox accent id="appearance-accent" defaultChecked/>
    Enable accent style
  </Label>
  <Label secondary htmlFor="appearance-secondary">
    <Checkbox secondary id="appearance-secondary" defaultChecked/>
    Enable secondary style
  </Label>
  <Label tertiary htmlFor="appearance-tertiary">
    <Checkbox tertiary id="appearance-tertiary" defaultChecked/>
    Enable tertiary style
  </Label>
  <Label success htmlFor="appearance-success">
    <Checkbox success id="appearance-success" defaultChecked/>
    Enable success style
  </Label>
  <Label danger htmlFor="appearance-danger">
    <Checkbox danger id="appearance-danger" defaultChecked/>
    Enable danger style
  </Label>
  <Label warning htmlFor="appearance-warning">
    <Checkbox warning id="appearance-warning" defaultChecked/>
    Enable warning style
  </Label>
  <Label info htmlFor="appearance-info">
    <Checkbox info id="appearance-info" defaultChecked/>
    Enable info style
  </Label>
  <Label link htmlFor="appearance-link">
    <Checkbox link id="appearance-link" defaultChecked/>
    Enable link style
  </Label>
  <Label inherit htmlFor="appearance-inherit">
    <Checkbox inherit id="appearance-inherit" defaultChecked/>
    Enable inherit style
  </Label>
</Row>

Shapes

Checkboxes support border radius styles: rounded (default), pill, and sharp.

Rounded (default)PillSharp

<Row flexWrap>
  <Label htmlFor="shape-rounded">
    <Checkbox id="shape-rounded" defaultChecked/>
    Rounded (default)
  </Label>
  <Label htmlFor="shape-pill">
    <Checkbox pill id="shape-pill" defaultChecked/>
    Pill
  </Label>
  <Label htmlFor="shape-sharp">
    <Checkbox sharp id="shape-sharp" defaultChecked/>
    Sharp
  </Label>
</Row>

Disabled

Use the disabled HTML attribute to prevent interaction.

Disabled (unchecked)Disabled (checked)

<Col>
  <Label htmlFor="disabled-unchecked">
    <Checkbox disabled id="disabled-unchecked"/>
    Disabled (unchecked)
  </Label>
  <Label htmlFor="disabled-checked">
    <Checkbox disabled defaultChecked id="disabled-checked"/>
    Disabled (checked)
  </Label>
</Col>

Controlled vs Uncontrolled

Checkbox forwards every HTML input attribute, so use defaultChecked for uncontrolled state and checked + onChange for controlled state.

Uncontrolled — initial value only, the input manages its own state:

Uncontrolled (defaultChecked)

<Label htmlFor="uncontrolled">
  <Checkbox defaultChecked id="uncontrolled"/>
  Uncontrolled (defaultChecked)
</Label>

Controlled — parent owns the value via useState:

const [checked, setChecked] = useState(false);

<Label htmlFor="controlled">
  <Checkbox
    id="controlled"
    checked={checked}
    onChange={(e) => setChecked(e.target.checked)}
  />
  Controlled ({checked ? 'on' : 'off'})
</Label>

Indeterminate State

Use the indeterminate prop for "select all" checkboxes that represent a partially selected group. The indeterminate state is visual only and does not affect the checked value.

<Checkbox indeterminate />

<Col>
  <Label htmlFor="select-all">
    <Checkbox id="select-all" indeterminate/>
    Select all (2 of 4 selected)
  </Label>
  <Col style={{ paddingLeft: 24 }}>
    <Label htmlFor="ind-1"><Checkbox id="ind-1" defaultChecked/> Item one</Label>
    <Label htmlFor="ind-2"><Checkbox id="ind-2" defaultChecked/> Item two</Label>
    <Label htmlFor="ind-3"><Checkbox id="ind-3"/> Item three</Label>
    <Label htmlFor="ind-4"><Checkbox id="ind-4"/> Item four</Label>
  </Col>
</Col>

Checkbox Group

Multiple labeled checkboxes working together.

Email notificationsSMS alertsPush notifications

<Col>
  <Label htmlFor="opt-1">
    <Checkbox id="opt-1" defaultChecked/>
    Email notifications
  </Label>
  <Label htmlFor="opt-2">
    <Checkbox id="opt-2"/>
    SMS alerts
  </Label>
  <Label htmlFor="opt-3">
    <Checkbox id="opt-3"/>
    Push notifications
  </Label>
</Col>

Checkbox Props

Prop	Category	Default	Description
`accent`	Appearance		Accent color appearance (rose)
`brand`	Appearance		Brand color appearance (blue)
`danger`	Appearance		Danger color appearance (red)
`info`	Appearance		Info color appearance (cyan)
`inherit`	Appearance		Inherit appearance from parent — suppresses own data-appearance/data-variant, uses parent's CSS variables
`link`	Appearance		Link color appearance (blue, for hyperlinks)
`primary`	Appearance	✓	Primary color appearance (gray)
`secondary`	Appearance		Secondary color appearance (gray)
`success`	Appearance		Success color appearance (green)
`tertiary`	Appearance		Tertiary color appearance
`warning`	Appearance		Warning color appearance (amber)
`disabled`	Disabled		Disable the component — reduces opacity, changes cursor to not-allowed, and prevents interaction
`pill`	Shape		Fully rounded corners (circular)
`rounded`	Shape	✓	Medium rounded corners (default)
`sharp`	Shape		No rounded corners (square)
`lg`	Size		Large size
`md`	Size	✓	Medium size (default)
`sm`	Size		Small size
`xl`	Size		Extra large size
`xs`	Size		Extra small size
`error`	Status		Show error state (red border/ring) for form validation
`filled`	Variant	✓	Filled variant - solid background with contrasting text color
`ghost`	Variant		Ghost variant - transparent background, no border, appearance-colored text, tinted hover background
`outline`	Variant		Outline variant - transparent background with border and colored text (default)

Layout & utility props (gap, padding, hide, items, justify, ...) — documented on Common Props

Prop	Category	Default	Description
`border`	Border	✓	Enable border on all sides
`borderB`	Border		Enable border on bottom
`borderL`	Border		Enable border on left
`borderR`	Border		Enable border on right
`borderT`	Border		Enable border on top
`borderX`	Border		Enable border on left and right
`borderY`	Border		Enable border on top and bottom
`noBorder`	Border		Disable all borders
`cursorDefault`	Cursor		Default cursor - standard arrow
`cursorMove`	Cursor		Move cursor - indicates draggable element
`cursorNone`	Cursor		No cursor - hides the cursor
`cursorNotAllowed`	Cursor		Not-allowed cursor - indicates disabled state
`cursorPointer`	Cursor	✓	Pointer cursor - indicates clickable element
`cursorText`	Cursor		Text cursor - indicates selectable text
`cursorWait`	Cursor		Wait cursor - indicates loading/processing
`block`	Display		Block display - takes full width, new line
`contents`	Display		Contents display - element's box is removed, children display as if parent didn't exist
`flex`	Display		Flex display - flexbox container
`grid`	Display		Grid display - CSS grid container
`hidden`	Display		Hidden display - element is not visible
`inline`	Display		Inline display - flows with text
`inlineBlock`	Display		Inline-block display - inline but with block properties
`inlineFlex`	Display		Inline-flex display - inline flexbox container
`inlineGrid`	Display		Inline-grid display - inline grid container
`table`	Display		Table display - behaves like table element
`tableCell`	Display		Table-cell display - behaves like td element
`focusVisible`	Focus Visible	✓	Enable focus-visible outline
`noFocusVisible`	Focus Visible		Disable focus-visible outline
`hAuto`	Height		Set height to auto
`hFit`	Height		Set height to fit-content
`hFull`	Height		Set height to 100%
`hScreen`	Height		Set height to 100vh (viewport height), removes max-height constraint
`desktopHide`	Hide		Hide element on desktop devices and below (max-desktop: 80rem)
`mobileHide`	Hide		Hide element on mobile devices and below (max-mobile: 48rem)
`tabletHide`	Hide		Hide element on tablet devices and below (max-tablet: 64rem)
`itemsBaseline`	Items		Align items to baseline
`itemsCenter`	Items		Align items to center
`itemsEnd`	Items		Align items to end (bottom/right)
`itemsStart`	Items		Align items to start (top/left)
`itemsStretch`	Items		Stretch items to fill container
`justifyAround`	Justify		Distribute items with space around them
`justifyBaseline`	Justify		Align items along their baseline on main axis
`justifyBetween`	Justify		Distribute items with space between them
`justifyCenter`	Justify		Center items along the main axis
`justifyEnd`	Justify		Pack items toward the end of the main axis
`justifyEvenly`	Justify		Distribute items with equal space around them
`justifyStart`	Justify		Pack items toward the start of the main axis
`justifyStretch`	Justify		Stretch items to fill the main axis
`overflowAuto`	Overflow		Auto overflow - show scrollbars if needed
`overflowClip`	Overflow		Clip overflow - hard clip without scrollbars
`overflowHidden`	Overflow		Hidden overflow - clip content without scrollbars
`overflowScroll`	Overflow		Scroll overflow - always show scrollbars
`overflowVisible`	Overflow		Visible overflow - content extends beyond bounds
`overflowXAuto`	Overflow		Auto overflow on X-axis only
`overflowXClip`	Overflow		Clip overflow on X-axis only
`overflowXHidden`	Overflow		Hidden overflow on X-axis only
`overflowXScroll`	Overflow		Scroll overflow on X-axis only
`overflowXVisible`	Overflow		Visible overflow on X-axis only
`overflowYAuto`	Overflow		Auto overflow on Y-axis only
`overflowYClip`	Overflow		Clip overflow on Y-axis only
`overflowYHidden`	Overflow		Hidden overflow on Y-axis only
`overflowYScroll`	Overflow		Scroll overflow on Y-axis only
`overflowYVisible`	Overflow		Visible overflow on Y-axis only
`absolute`	Position		Absolute positioning
`fixed`	Position		Fixed positioning
`relative`	Position		Relative positioning
`static`	Position		Static positioning
`sticky`	Position		Sticky positioning
`responsive`	Responsive		Enable responsive sizing - uses breakpoint-specific classes for font size, padding, and gap
`noRing`	Ring	✓	Disable focus ring
`ring`	Ring		Enable focus ring
`noShadow`	Shadow	✓	Disable drop shadow
`shadow`	Shadow		Enable drop shadow
`noTransition`	Transition		Disable transitions for instant state changes
`transition`	Transition		Enable smooth transitions between states
`transparent`	Transparent		Disable background color - makes component background transparent
`wAuto`	Width		Set width to auto
`wFit`	Width		Set width to fit-content
`wFull`	Width		Set width to 100%
`wScreen`	Width		Set width to 100vw (viewport width), removes max-width constraint