Checkbox

Checkbox component for selecting multiple options with various styles and group support.

Import

import { Checkbox } from 'asterui'

Examples

Basic Usage

Simple checkbox with label.

</>

Accept terms and conditions

import { Checkbox } from 'asterui'

function App() {
  return (
      <Checkbox>Accept terms and conditions</Checkbox>
    )
}

export default App

Colors

Different checkbox colors for various contexts.

</>

PrimarySecondaryAccentSuccessWarningInfoError

import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="vertical" size="sm">
        <Checkbox color="primary" defaultChecked>Primary</Checkbox>
        <Checkbox color="secondary" defaultChecked>Secondary</Checkbox>
        <Checkbox color="accent" defaultChecked>Accent</Checkbox>
        <Checkbox color="success" defaultChecked>Success</Checkbox>
        <Checkbox color="warning" defaultChecked>Warning</Checkbox>
        <Checkbox color="info" defaultChecked>Info</Checkbox>
        <Checkbox color="error" defaultChecked>Error</Checkbox>
      </Space>
    )
}

export default App

Sizes

Five checkbox sizes from xs to xl.

</>

XSSMMDLGXL

import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="md" align="center">
        <Checkbox size="xs" defaultChecked>XS</Checkbox>
        <Checkbox size="sm" defaultChecked>SM</Checkbox>
        <Checkbox size="md" defaultChecked>MD</Checkbox>
        <Checkbox size="lg" defaultChecked>LG</Checkbox>
        <Checkbox size="xl" defaultChecked>XL</Checkbox>
      </Space>
    )
}

export default App

Disabled

Disabled checkbox states.

</>

DisabledDisabled Checked

import { Checkbox, Space } from 'asterui'

function App() {
  return (
      <Space direction="horizontal" size="md">
        <Checkbox disabled>Disabled</Checkbox>
        <Checkbox disabled defaultChecked>Disabled Checked</Checkbox>
      </Space>
    )
}

export default App

Indeterminate

Indeterminate state for check-all functionality.

</>

Select All

Item 1Item 2Item 3

import { Checkbox, Space } from 'asterui'
import { useState } from 'react'

function App() {
  const [items, setItems] = useState([true, false, true])
  const allChecked = items.every(Boolean)
  const someChecked = items.some(Boolean) && !allChecked
  
  const handleSelectAll = () => {
    setItems(allChecked ? [false, false, false] : [true, true, true])
  }
  
  return (
      <Space direction="vertical" size="sm">
        <Checkbox
          checked={allChecked}
          indeterminate={someChecked}
          onChange={handleSelectAll}
          className="font-medium"
        >
          Select All
        </Checkbox>
        <div className="ml-6">
          <Space direction="vertical" size="xs">
            {['Item 1', 'Item 2', 'Item 3'].map((item, i) => (
              <Checkbox
                key={i}
                checked={items[i]}
                onChange={() => {
                  const newItems = [...items]
                  newItems[i] = !newItems[i]
                  setItems(newItems)
                }}
              >
                {item}
              </Checkbox>
            ))}
          </Space>
        </div>
      </Space>
    )
}

export default App

Checkbox Group

Group multiple checkboxes with shared state.

</>

AppleBananaOrangeMango

import { Checkbox, Modal } from 'asterui'

function App() {
  const options = [
    { label: 'Apple', value: 'apple' },
    { label: 'Banana', value: 'banana' },
    { label: 'Orange', value: 'orange' },
    { label: 'Mango', value: 'mango' },
  ]
  
  return (
      <Checkbox.Group
        options={options}
        defaultValue={['apple', 'orange']}
        onChange={(values) => Modal.info({ title: 'Selected', content: values.join(', ') })}
      />
    )
}

export default App

Group with Options

Generate checkboxes from options array with disabled support.

</>

ReadWriteDelete

import { Checkbox } from 'asterui'

function App() {
  const options = [
    { label: 'Read', value: 'read' },
    { label: 'Write', value: 'write' },
    { label: 'Delete', value: 'delete', disabled: true },
  ]
  
  return (
      <Checkbox.Group
        options={options}
        defaultValue={['read']}
      />
    )
}

export default App

Group Direction

Horizontal and vertical group layouts.

</>

Horizontal (default)

Option AOption BOption C

Vertical

Option AOption BOption C

import { Checkbox, Space } from 'asterui'

function App() {
  const options = ['Option A', 'Option B', 'Option C']
  
  return (
      <Space direction="vertical" size="lg">
        <div>
          <p className="text-sm font-medium mb-2">Horizontal (default)</p>
          <Checkbox.Group options={options} direction="horizontal" defaultValue={['Option A']} />
        </div>
        <div>
          <p className="text-sm font-medium mb-2">Vertical</p>
          <Checkbox.Group options={options} direction="vertical" defaultValue={['Option B']} />
        </div>
      </Space>
    )
}

export default App

Controlled

Controlled checkbox with external state management.

</>

Controlled checkbox

Checked: No

import { Checkbox, Space } from 'asterui'
import { useState } from 'react'

function App() {
  const [checked, setChecked] = useState(false)
  
  return (
      <Space direction="vertical" size="sm">
        <Checkbox
          checked={checked}
          onChange={(e) => setChecked(e.target.checked)}
        >
          Controlled checkbox
        </Checkbox>
        <p className="text-sm text-base-content/70">
          Checked: {checked ? 'Yes' : 'No'}
        </p>
      </Space>
    )
}

export default App

Swap Mode

Toggle between two visual states with animation effects.

</>

😀

😴

ON

OFF

import { Checkbox, Space } from 'asterui'
import { SpeakerWaveIcon, SpeakerXMarkIcon } from '@aster-ui/icons/solid'
import { useState } from 'react'

function App() {
  const [volume, setVolume] = useState(true)
  
  return (
      <Space size="lg">
        <Checkbox
          checked={volume}
          onChange={(e) => setVolume(e.target.checked)}
          swap={{
            on: <SpeakerWaveIcon size={32} />,
            off: <SpeakerXMarkIcon size={32} />,
          }}
        />
        <Checkbox
          swap={{
            on: <span className="text-2xl">😀</span>,
            off: <span className="text-2xl">😴</span>,
            effect: 'rotate',
          }}
        />
        <Checkbox
          swap={{
            on: <span className="text-xl font-bold text-success">ON</span>,
            off: <span className="text-xl font-bold text-error">OFF</span>,
            effect: 'flip',
          }}
        />
      </Space>
    )
}

export default App

API

Checkbox

Property	Description	Type	Default
checked	Controlled checked state	boolean	-
defaultChecked	Default checked state	boolean	-
disabled	Disable the checkbox	boolean	false
indeterminate	Indeterminate state (partial selection)	boolean	false
size	Checkbox size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	-
color	Checkbox color	'primary' | 'secondary' | 'accent' | 'neutral' | 'success' | 'warning' | 'info' | 'error'	-
swap	Swap mode configuration	CheckboxSwapConfig	-
value	Value when used in a group	string | number	-
onChange	Change event handler	(e: ChangeEvent) => void	-
name	HTML name attribute for the input	string	-
autoFocus	Auto focus on mount	boolean	false
className	Additional CSS classes	string	-
children	Label content (automatically wrapped in label element)	ReactNode	-

Checkbox.Group

Property	Description	Type	Default
value	Controlled selected values	(string | number)[]	-
defaultValue	Default selected values	(string | number)[]	-
onChange	Selection change callback	(values: (string | number)[]) => void	-
disabled	Disable all checkboxes	boolean	false
options	Checkbox options	(string | number | CheckboxOptionType)[]	-
direction	Layout direction	'horizontal' | 'vertical'	'vertical'
name	HTML name attribute for all checkboxes (for form submission)	string	-
children	Manual checkbox elements	ReactNode	-

CheckboxSwapConfig

Property	Description	Type	Default
on	Content shown when checked	ReactNode	-
off	Content shown when unchecked	ReactNode	-
effect	Animation effect	'rotate' | 'flip'	-

CheckboxOptionType

Property	Description	Type	Default
label	Option label	ReactNode	-
value	Option value	string | number	-
disabled	Disable this option	boolean	false

Accessibility

• Uses native checkbox input for keyboard and screen reader support
• Properly associates labels with checkboxes
• Indeterminate state is communicated via the native indeterminate property
• Disabled state prevents interaction and is communicated to assistive technologies
• Focus states are visible for keyboard navigation