Checkbox

A control that allows the user to toggle between checked and not checked.

Code

import {
  Checkbox,
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldTitle,
  Label,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:max-w-sm">
      <Field orientation="horizontal">
        <Checkbox id="terms-checkbox" name="terms-checkbox" />
        <Label htmlFor="terms-checkbox">Accept terms and conditions</Label>
      </Field>
      <Field orientation="horizontal">
        <Checkbox
          id="terms-checkbox-2"
          name="terms-checkbox-2"
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor="terms-checkbox-2">
            Accept terms and conditions
          </FieldLabel>
          <FieldDescription>
            By clicking this checkbox, you agree to the terms.
          </FieldDescription>
        </FieldContent>
      </Field>
      <Field orientation="horizontal" data-disabled>
        <Checkbox id="toggle-checkbox" name="toggle-checkbox" disabled />
        <FieldLabel htmlFor="toggle-checkbox">Enable notifications</FieldLabel>
      </Field>
      <FieldLabel>
        <Field orientation="horizontal">
          <Checkbox id="toggle-checkbox-2" name="toggle-checkbox-2" />
          <FieldContent>
            <FieldTitle>Enable notifications</FieldTitle>
            <FieldDescription>
              You can enable or disable notifications at any time.
            </FieldDescription>
          </FieldContent>
        </Field>
      </FieldLabel>
    </FieldGroup>
  );
}

Checked State

Use defaultChecked for uncontrolled checkboxes, or checked and onCheckedChange to control the state.

Code

import { Checkbox } from "@falcon/ui-kit";
import { useState } from "react";

export function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <Checkbox
      aria-label="Accept terms and conditions"
      checked={checked}
      onCheckedChange={setChecked}
    />
  );
}

Invalid State

Set aria-invalid on the checkbox and data-invalid on the field wrapper to show the invalid styles.

Code

import { Checkbox, Field, FieldGroup, FieldLabel } from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:mx-auto tw:w-56">
      <Field orientation="horizontal" data-invalid>
        <Checkbox
          id="terms-checkbox-invalid"
          name="terms-checkbox-invalid"
          aria-invalid
        />
        <FieldLabel htmlFor="terms-checkbox-invalid">
          Accept terms and conditions
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

Basic

Pair the checkbox with Field and FieldLabel for proper layout and labeling.

Code

import { Checkbox, Field, FieldGroup, FieldLabel } from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:mx-auto tw:w-56">
      <Field orientation="horizontal">
        <Checkbox id="terms-checkbox-basic" name="terms-checkbox-basic" />
        <FieldLabel htmlFor="terms-checkbox-basic">
          Accept terms and conditions
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

Description

Use FieldContent and FieldDescription for helper text.

Code

import {
  Checkbox,
  Field,
  FieldContent,
  FieldDescription,
  FieldGroup,
  FieldLabel,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:mx-auto tw:w-72">
      <Field orientation="horizontal">
        <Checkbox
          id="terms-checkbox-desc"
          name="terms-checkbox-desc"
          defaultChecked
        />
        <FieldContent>
          <FieldLabel htmlFor="terms-checkbox-desc">
            Accept terms and conditions
          </FieldLabel>
          <FieldDescription>
            By clicking this checkbox, you agree to the terms and conditions.
          </FieldDescription>
        </FieldContent>
      </Field>
    </FieldGroup>
  );
}

Disabled

Use the disabled prop to prevent interaction and add the data-disabled attribute to the <Field> component for disabled styles.

Code

import { Checkbox, Field, FieldGroup, FieldLabel } from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldGroup className="tw:mx-auto tw:w-56">
      <Field orientation="horizontal" data-disabled>
        <Checkbox
          id="toggle-checkbox-disabled"
          name="toggle-checkbox-disabled"
          disabled
        />
        <FieldLabel htmlFor="toggle-checkbox-disabled">
          Enable notifications
        </FieldLabel>
      </Field>
    </FieldGroup>
  );
}

Group

Use multiple fields to create a checkbox list.

Code

import {
  Checkbox,
  Field,
  FieldDescription,
  FieldGroup,
  FieldLabel,
  FieldLegend,
  FieldSet,
} from "@falcon/ui-kit";

export function Example() {
  return (
    <FieldSet>
      <FieldLegend variant="label">
        Show these sections on the dashboard:
      </FieldLegend>
      <FieldDescription>
        Select the sections you want to show on the dashboard.
      </FieldDescription>
      <FieldGroup className="tw:gap-3">
        <Field orientation="horizontal">
          <Checkbox
            id="dashboard-pref-9k2-agronomy-orders-ljj-checkbox"
            name="dashboard-pref-9k2-agronomy-orders-ljj-checkbox"
            defaultChecked
          />
          <FieldLabel
            htmlFor="dashboard-pref-9k2-agronomy-orders-ljj-checkbox"
            className="tw:font-normal"
          >
            Agronomy orders
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id="dashboard-pref-9k2-prepay-balances-1yg-checkbox"
            name="dashboard-pref-9k2-prepay-balances-1yg-checkbox"
            defaultChecked
          />
          <FieldLabel
            htmlFor="dashboard-pref-9k2-prepay-balances-1yg-checkbox"
            className="tw:font-normal"
          >
            Prepay balances
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id="dashboard-pref-9k2-bookings-fzt-checkbox"
            name="dashboard-pref-9k2-bookings-fzt-checkbox"
          />
          <FieldLabel
            htmlFor="dashboard-pref-9k2-bookings-fzt-checkbox"
            className="tw:font-normal"
          >
            Bookings
          </FieldLabel>
        </Field>
        <Field orientation="horizontal">
          <Checkbox
            id="dashboard-pref-9k2-invoices-6l2-checkbox"
            name="dashboard-pref-9k2-invoices-6l2-checkbox"
          />
          <FieldLabel
            htmlFor="dashboard-pref-9k2-invoices-6l2-checkbox"
            className="tw:font-normal"
          >
            Invoices
          </FieldLabel>
        </Field>
      </FieldGroup>
    </FieldSet>
  );
}

Table

Code

import {
  Checkbox,
  Table,
  TableBody,
  TableCell,
  TableHead,
  TableHeader,
  TableRow,
} from "@falcon/ui-kit";
import { useState } from "react";

const tableData = [
  {
    id: "1",
    name: "Sarah Chen",
    email: "sarah.chen@example.com",
    role: "Admin",
  },
  {
    id: "2",
    name: "Marcus Rodriguez",
    email: "marcus.rodriguez@example.com",
    role: "User",
  },
  {
    id: "3",
    name: "Priya Patel",
    email: "priya.patel@example.com",
    role: "User",
  },
  {
    id: "4",
    name: "David Kim",
    email: "david.kim@example.com",
    role: "Editor",
  },
];

export function Example() {
  const [selectedRows, setSelectedRows] = useState<Set<string>>(new Set(["1"]));

  const selectAll = selectedRows.size === tableData.length;

  function handleSelectAll(checked: boolean) {
    if (checked) {
      setSelectedRows(new Set(tableData.map((row) => row.id)));
    } else {
      setSelectedRows(new Set());
    }
  }

  function handleSelectRow(id: string, checked: boolean) {
    const newSelected = new Set(selectedRows);
    if (checked) {
      newSelected.add(id);
    } else {
      newSelected.delete(id);
    }
    setSelectedRows(newSelected);
  }

  return (
    <Table>
      <TableHeader>
        <TableRow>
          <TableHead className="tw:w-8">
            <Checkbox
              id="select-all-checkbox"
              name="select-all-checkbox"
              aria-label="Select all rows"
              checked={selectAll}
              onCheckedChange={handleSelectAll}
            />
          </TableHead>
          <TableHead>Name</TableHead>
          <TableHead>Email</TableHead>
          <TableHead>Role</TableHead>
        </TableRow>
      </TableHeader>
      <TableBody>
        {tableData.map((row) => (
          <TableRow
            key={row.id}
            data-state={selectedRows.has(row.id) ? "selected" : undefined}
          >
            <TableCell>
              <Checkbox
                id={`row-${row.id}-checkbox`}
                name={`row-${row.id}-checkbox`}
                aria-label={`Select ${row.name}`}
                checked={selectedRows.has(row.id)}
                onCheckedChange={(checked) =>
                  handleSelectRow(row.id, checked === true)
                }
              />
            </TableCell>
            <TableCell className="tw:font-medium">{row.name}</TableCell>
            <TableCell>{row.email}</TableCell>
            <TableCell>{row.role}</TableCell>
          </TableRow>
        ))}
      </TableBody>
    </Table>
  );
}

API

Checkbox

Renders a <span> element, a hidden form input, and a checkmark indicator. There is no parent/child checkbox-group API; control a select-all checkbox with checked, indeterminate, and onCheckedChange.

Props

checked

checked?: boolean

Whether the checkbox is currently ticked. Use defaultChecked when uncontrolled.

className

className?: string

CSS class applied to the checkbox element.

defaultChecked

defaultChecked?: boolean

Whether the checkbox is initially ticked. Use checked when controlled.

disabled

disabled?: boolean

Whether the checkbox ignores user interaction.

form

form?: string

ID of the form that owns the hidden input.

id

id?: string

ID of the hidden input.

indeterminate

indeterminate?: boolean

Whether the checkbox is in a mixed state.

inputRef

inputRef?: React.Ref<HTMLInputElement>

Ref for the hidden input element.

name

name?: string

Form field name.

nativeButton

nativeButton?: boolean

Set to true when render returns a native button.

onCheckedChange

onCheckedChange?: ((checked: boolean, eventDetails: CheckboxRootChangeEventDetails) => void)

Called when the checkbox is ticked or unticked.

readOnly

readOnly?: boolean

Whether users can focus but not change the checkbox.

render

render?: React.ReactElement<any, string | React.JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, CheckboxRootState>

Allows replacing the checkbox element or composing it with another component.

required

required?: boolean

Whether the checkbox must be ticked before its form can submit.

style

style?: React.CSSProperties | ((state: CheckboxRootState) => React.CSSProperties | undefined)

Style applied to the checkbox element.

uncheckedValue

uncheckedValue?: string

Form value submitted while the checkbox is unchecked.

value

value?: string

Form value submitted while the checkbox is checked.