Checkbox

A box for turning an option on or off.

Accept terms and conditions

Usage

import { Checkbox } from '@appica/ui-react/checkbox'

<label className="flex items-center gap-2">
  <Checkbox defaultChecked />
  Accept terms and conditions
</label>

Checkbox renders only the box — it has no text of its own. Wrap it and its label in a single <label> so clicking either toggles the box and assistive tech announces them together; no id/htmlFor wiring needed. Use it uncontrolled with defaultChecked, or controlled with checked + onCheckedChange. The animated check and squish are skipped when the user prefers reduced motion.

To manage several related checkboxes as one value, reach for CheckboxGroup.

Examples

States

A checkbox is unchecked, checked, or indeterminate (a mixed state, drawn as a dash). Any of them can also be disabled.

import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxStates() {
  return (
    <div className="flex flex-wrap items-center gap-6 text-sm select-none">
      <label className="flex items-center gap-2">
        <Checkbox />
        Unchecked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox defaultChecked />
        Checked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox indeterminate />
        Indeterminate
      </label>
      <label className="text-foreground-muted flex items-center gap-2">
        <Checkbox disabled />
        Disabled
      </label>
      <label className="text-foreground-muted flex items-center gap-2">
        <Checkbox disabled defaultChecked />
        Disabled checked
      </label>
      <label className="flex items-center gap-2">
        <Checkbox aria-invalid />
        Error
      </label>
    </div>
  )
}

Sizing

Checkbox is sized in em, so it scales with the surrounding font size — set a text-* class on the wrapping <label> and the box and text grow together. It won't shrink below a 16px floor.

text-basetext-lgtext-xl

import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxSizing() {
  return (
    <div className="flex flex-col items-start gap-4 select-none">
      <label className="flex items-center gap-2 text-base">
        <Checkbox defaultChecked />
        text-base
      </label>
      <label className="flex items-center gap-2.5 text-lg">
        <Checkbox defaultChecked />
        text-lg
      </label>
      <label className="flex items-center gap-3 text-xl">
        <Checkbox defaultChecked />
        text-xl
      </label>
    </div>
  )
}

With a label and description

Put a title and supporting text beside the box. Keeping both inside the <label> means the whole block is one click target.

Enable notificationsReceive emails about new activity on your account. You can turn this off any time.

import { Checkbox } from '@appica/ui-react/checkbox'

export default function CheckboxWithLabel() {
  return (
    <label className="flex max-w-sm items-start gap-2.5 select-none">
      <Checkbox defaultChecked className="mt-1" />
      <span className="flex flex-col">
        <span className="text-foreground-intense font-medium">Enable notifications</span>
        <span className="text-foreground-muted text-sm">
          Receive emails about new activity on your account. You can turn this off any time.
        </span>
      </span>
    </label>
  )
}

Checkbox group

CheckboxGroup shares a single array value across its children, so you read and set the whole set at once instead of tracking each box. Each child is matched to the value array by its name. It lays out vertically by default; pass orientation="horizontal" to wrap into a row.

ToppingsExtra cheeseMushroomsOlivesOnions

import { CheckboxGroup } from '@appica/ui-react/checkbox-group'
import { Checkbox } from '@appica/ui-react/checkbox'

const toppings = [
  { name: 'cheese', label: 'Extra cheese' },
  { name: 'mushrooms', label: 'Mushrooms' },
  { name: 'olives', label: 'Olives' },
  { name: 'onions', label: 'Onions' },
]

export default function CheckboxGroupExample() {
  return (
    <CheckboxGroup aria-labelledby="toppings-label" defaultValue={['cheese', 'olives']}>
      <span id="toppings-label" className="text-foreground mb-1 text-sm font-medium">
        Toppings
      </span>
      {toppings.map((topping) => (
        <label key={topping.name} className="flex items-center gap-2 text-sm select-none">
          <Checkbox name={topping.name} />
          {topping.label}
        </label>
      ))}
    </CheckboxGroup>
  )
}

Select all (parent checkbox)

Give the group the full list of child values via allValues and mark one child parent. When some — but not all — children are checked, the group drives the parent into the indeterminate state automatically; ticking the parent checks every child, and clearing it unchecks them.

Permissions

ReadWriteDelete

'use client'

import * as React from 'react'
import { CheckboxGroup } from '@appica/ui-react/checkbox-group'
import { Checkbox } from '@appica/ui-react/checkbox'

const permissions = [
  { name: 'read', label: 'Read' },
  { name: 'write', label: 'Write' },
  { name: 'delete', label: 'Delete' },
]

const allValues = permissions.map((permission) => permission.name)

export default function CheckboxSelectAll() {
  const [value, setValue] = React.useState<string[]>(['read'])

  return (
    <CheckboxGroup aria-labelledby="permissions-label" allValues={allValues} value={value} onValueChange={setValue}>
      <label className="flex items-center gap-2 text-sm font-medium select-none">
        <Checkbox parent />
        <span id="permissions-label">Permissions</span>
      </label>
      <div className="flex flex-col gap-2 pl-6">
        {permissions.map((permission) => (
          <label key={permission.name} className="flex items-center gap-2 text-sm select-none">
            <Checkbox name={permission.name} />
            {permission.label}
          </label>
        ))}
      </div>
    </CheckboxGroup>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior — roving focus, popup placement, and the like — follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

تفضيلات الإشعاراتتحديثات البريد الإلكترونيأخبار المنتجالنشرة الأسبوعية

API reference

Checkbox and CheckboxGroup wrap Base UI's Checkbox and CheckboxGroup. Each forwards ref, aria-*, and its native attributes; Checkbox exposes data-* state attributes (data-checked, data-unchecked, data-indeterminate, data-disabled, data-readonly, …) for styling and CheckboxGroup renders a <div role="group">. See the Base UI docs for the complete API.

Checkbox

Prop	Type	Default	Description
`checked`	`boolean`	—	Controlled checked state. Pair with `onCheckedChange`.
`defaultChecked`	`boolean`	`false`	Uncontrolled initial checked state.
`onCheckedChange`	`(checked: boolean, details) => void`	—	Fires when the box is ticked or unticked.
`indeterminate`	`boolean`	`false`	Render the mixed state (dash). Reported to assistive tech as `aria-checked="mixed"`.
`parent`	`boolean`	`false`	Inside a `CheckboxGroup`, makes this the "select all" box driven by the children (needs group `allValues`).
`name`	`string`	—	Field name on form submit; also how a `CheckboxGroup` matches this box to its value array.
`value`	`string`	—	The value submitted with the form when the box is checked.
`uncheckedValue`	`string`	—	The value submitted with the form when the box is unchecked.
`form`	`string`	—	`id` of the form that owns the hidden input, when it isn't a descendant.
`disabled`	`boolean`	`false`	Removes the box from the tab order and ignores interaction.
`readOnly`	`boolean`	`false`	Focusable but not toggleable.
`required`	`boolean`	`false`	Must be checked before its form submits.
`nativeButton`	`boolean`	`false`	Whether the element passed to `render` is a native `<button>`.
`inputRef`	`Ref<HTMLInputElement>`	—	Ref to the hidden `<input>` element backing the checkbox.
`id`	`string`	—	`id` of the rendered element.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the rendered element, or compose it with another component.
`className`	`string \| ((state) => string)`	—	Extra classes on the box, merged via `tailwind-merge`. May be a function of state.
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

CheckboxGroup

Shares one value array across the checkboxes nested inside it.

Prop	Type	Default	Description
`value`	`string[]`	—	Controlled array of checked child `name`s. Pair with `onValueChange`.
`defaultValue`	`string[]`	—	Uncontrolled initial set of checked children.
`onValueChange`	`(value: string[], details) => void`	—	Fires with the next array whenever a child toggles.
`allValues`	`string[]`	—	Every child value — required to drive a `parent` "select all" checkbox.
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	Stack the boxes in a column, or wrap them into a row.
`disabled`	`boolean`	`false`	Disables every checkbox in the group.
`render`	`ReactElement \| ((props, state) => ReactElement)`	—	Replace the group element, or compose it with another component.
`className`	`string \| ((state) => string)`	—	Extra classes, merged via `tailwind-merge` (override the default `flex` layout here).
`style`	`CSSProperties \| ((state) => CSSProperties)`	—	Inline styles, optionally derived from state.

Accessibility

Renders with role="checkbox". Space toggles it; Tab moves focus to and from it.
A checkbox needs an accessible name — wrap it in a <label> together with its text (as shown above), or give it an aria-label.
indeterminate is announced as aria-checked="mixed", distinct from checked and unchecked.
CheckboxGroup renders a <div role="group">; name it with aria-label or aria-labelledby since a group can't use a wrapping <label>.
disabled removes the box from the tab order and exposes data-disabled for styling.
The check/squish animations honour prefers-reduced-motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Checkbox

Usage

Examples

States

Sizing

With a label and description

Checkbox group

Select all (parent checkbox)

RTL

API reference

Checkbox

CheckboxGroup

Accessibility