Skip to content

Checkbox

A control that allows the user to toggle between checked and not checked. It uses DOM primitives like native checkbox inputs, labels, fieldsets, and legends.

Source Code

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Accept terms and conditions" />
));

Import

import { Checkbox } from "areia";

Usage

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Remember me" />
));

Examples

Default

Checkbox with a built-in label. The label automatically displays in a horizontal layout with the checkbox before the label.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Accept terms and conditions" />
));

Checked

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Enable notifications" checked />
));

Indeterminate

Used for “select all” patterns when some but not all items are selected.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Select all" indeterminate />
));

Label First Layout

Use controlFirst: false to place the label before the checkbox.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Enable notifications" controlFirst={false} />
));

Disabled

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Disabled" disabled />
));

Error

The error variant provides visual styling. For error messages, use Checkbox.Group.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox label="Required field" variant="error" required />
));

Without Visible Label

When a checkbox does not have visible label text, provide an accessible name with aria-label.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox aria-label="Select row" />
));

Checkbox Group

Group multiple checkboxes with a legend and description. Use Checkbox.Group and Checkbox.Item.

Notification preferences

Choose how you want to receive updates.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox.Group
    legend="Notification preferences"
    description="Choose how you want to receive updates."
  >
    <Checkbox.Item
      label="Email notifications"
      value="email"
      checked
    />
    <Checkbox.Item label="SMS notifications" value="sms" />
    <Checkbox.Item label="Product updates" value="updates" />
  </Checkbox.Group>
));

Checkbox Group with Error

Show validation errors at the group level.

Notification preferences

Select at least one notification method.

import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox.Group
    legend="Notification preferences"
    error="Select at least one notification method."
  >
    <Checkbox.Item
      label="Email notifications"
      value="email"
      variant="error"
    />
    <Checkbox.Item
      label="SMS notifications"
      value="sms"
      variant="error"
    />
  </Checkbox.Group>
));

Visually Hidden Legend

Use Checkbox.Legend with class: "sr-only" to keep the legend accessible to screen readers while hiding it visually. This is useful when the group is already labeled by nearby visible text.

Notification preferences

Notification preferences 
import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <div class="flex flex-col gap-3">
    <p class="text-base font-medium text-areia-default">
      Notification preferences
    </p>
    <Checkbox.Group>
      <Checkbox.Legend
        label="Notification preferences"
        class="sr-only"
      />
      <Checkbox.Item
        label="Email notifications"
        value="email"
        checked
      />
      <Checkbox.Item label="SMS notifications" value="sms" />
    </Checkbox.Group>
  </div>
));

Custom Legend Styling

Use Checkbox.Legend when you need custom typography, colors, or layout instead of the legend string prop.

Notification preferences 
import ilha from "ilha";
import { Checkbox } from "areia";

export default ilha.render(() => (
  <Checkbox.Group>
    <Checkbox.Legend
      label="Notification preferences"
      class="text-sm uppercase tracking-wide text-areia-subtle"
    />
    <Checkbox.Item
      label="Email notifications"
      value="email"
      checked
    />
    <Checkbox.Item label="SMS notifications" value="sms" />
  </Checkbox.Group>
));

API Reference

Checkbox

Single checkbox component with built-in label and horizontal layout.

PropTypeDefaultDescription
variant"default" | "error""default"Visual variant.
labelunknown-Label content for the checkbox.
labelTooltipstring-Tooltip text rendered as a native title on the label text.
controlFirstbooleantrueWhen true, checkbox appears before label. When false, label appears before checkbox.
checkedboolean-Whether the checkbox is checked.
indeterminateboolean-Whether the checkbox is in an indeterminate visual state.
disabledboolean-Whether the checkbox is disabled.
namestring-Name for form submission.
valuestring-Value for form submission.
requiredboolean-Whether the field is required.
classstring-Additional CSS classes applied to the checkbox control.
classNamestring-Alias for class.

Checkbox.Group

Wrapper for multiple checkboxes with legend, description, and error support.

PropTypeDefaultDescription
legendunknown-Legend content for the group.
first argumentunknown[]-Checkbox item markup when no group props are needed.
second argumentunknown[]-Checkbox item markup, usually Checkbox.Item(...) calls.
childrenunknown-Inline checkbox item markup. Prefer the second argument for groups.
errorunknown-Error message for the group.
descriptionunknown-Helper text for the group.
disabledboolean-Whether all controls in the fieldset are disabled.
classstring-Additional CSS classes.
classNamestring-Alias for class.

Checkbox.Legend

Composable legend sub-component for Checkbox.Group. Use it instead of the legend prop when you need custom legend styling.

PropTypeDefaultDescription
labelunknown-Legend content.
classstring-Additional CSS classes.
classNamestring-Alias for class.

Checkbox.Item

Individual checkbox within Checkbox.Group. It accepts the same props as Checkbox, plus value for form submission.

Accessibility

Label Requirement

Single checkboxes should have a visible label, an aria-label, or an aria-labelledby value so assistive technologies can announce their purpose.

Keyboard Navigation

Because this component uses native <input type="checkbox">, Space toggles the checkbox and Tab moves focus between controls.

Screen Readers

Checkbox.Group uses semantic <fieldset> and <legend> elements for proper grouping announcements.