Components

Checkbox

A box that is ticked, empty, or mixed

Import

import { Checkbox, CheckboxField } from "@nyte-ai/ui/checkbox";

CheckboxField is a checkbox in a labelled row, with an optional description. For a setting that applies on change, use Switch.

Usage

indeterminate draws a dash, for a box over a partly ticked list.

Examples

const [archived, setArchived] = useState(false);

<label>
  <Checkbox checked={archived} onCheckedChange={setArchived} />
  Show archived chats
</label>;

All files viewedsidebar.tsxrow.tsxcheckbox.tsx

const [viewed, setViewed] = useState<readonly string[]>(["row.tsx"]);

<>
  <label>
    <Checkbox
      checked={viewed.length === files.length}
      indeterminate={viewed.length > 0 && viewed.length < files.length}
      onCheckedChange={(checked) => setViewed(checked ? files : [])}
    />
    All files viewed
  </label>
  {files.map((file) => (
    <label key={file}>
      <Checkbox
        checked={viewed.includes(file)}
        onCheckedChange={(checked) =>
          setViewed((current) =>
            checked ? [...current, file] : current.filter((path) => path !== file),
          )
        }
      />
      {file}
    </label>
  ))}
</>;

Field

const [archived, setArchived] = useState(false);

<CheckboxField
  label="Show archived chats"
  description="Archived chats appear below the active ones"
  checked={archived}
  onCheckedChange={setArchived}
/>;

Props

Checkbox

Takes every Base UI Checkbox.Root prop except children. className and style take plain values, not functions of state. The indicator is built in.

Prop	Type	Default	Description
`size`	`"md" \| "lg"`	`"md"`
`className`, `style`, `xstyle`	see Theming

The reference table below comes from Base UI, MIT, © Material-UI SAS.

Represents the checkbox itself. Renders a <span> element and a hidden <input> beside.

Root Props:

Prop	Type	Default	Description
name	`string`	`undefined`	Identifies the field when a form is submitted.
defaultChecked	`boolean`	`false`	Whether the checkbox is initially ticked. To render a controlled checkbox, use the `checked` prop instead.
checked	`boolean`	`undefined`	Whether the checkbox is currently ticked. To render an uncontrolled checkbox, use the `defaultChecked` prop instead.
onCheckedChange	`((checked: boolean, eventDetails: Checkbox.Root.ChangeEventDetails) => void)`	-	Event handler called when the checkbox is ticked or unticked.
indeterminate	`boolean`	`false`	Whether the checkbox is in a mixed state: neither ticked, nor unticked.
value	`string`	-	The checkbox's value. Identifies it within a Checkbox Group, falling back to `name` when omitted. When submitting a form, a checked box submits `value`; with no `value`, it submits the native "on".
form	`string`	-	Identifies the form that owns the hidden input. Useful when the checkbox is rendered outside the form.
nativeButton	`boolean`	`false`	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `true` if the rendered element is a native button.
parent	`boolean`	`false`	Whether the checkbox controls a group of child checkboxes. Must be used in a Checkbox Group.
uncheckedValue	`string`	-	The value submitted with the form when the checkbox is unchecked. By default, unchecked checkboxes do not submit any value, matching native checkbox behavior.
disabled	`boolean`	`false`	Whether the component should ignore user interaction.
readOnly	`boolean`	`false`	Whether the user should be unable to tick or untick the checkbox.
required	`boolean`	`false`	Whether the user must tick the checkbox before submitting a form.
inputRef	`React.Ref<HTMLInputElement>`	-	A ref to access the hidden `<input>` element.
id	`string`	-	The id of the input element.
className	`string \| ((state: Checkbox.Root.State) => string \| undefined)`	-	CSS class applied to the element, or a function that returns a class based on the component's state.
style	`React.CSSProperties \| ((state: Checkbox.Root.State) => React.CSSProperties \| undefined)`	-	Style applied to the element, or a function that returns a style object based on the component's state.
render	`ReactElement \| ((props: HTMLProps, state: Checkbox.Root.State) => ReactElement)`	-	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Root Data Attributes:

Attribute	Type	Description
data-checked	-	Present when the checkbox is checked.
data-unchecked	-	Present when the checkbox is not checked.
data-disabled	-	Present when the checkbox is disabled.
data-readonly	-	Present when the checkbox is readonly.
data-required	-	Present when the checkbox is required.
data-valid	-	Present when the checkbox is in a valid state (when wrapped in Field.Root).
data-invalid	-	Present when the checkbox is in an invalid state (when wrapped in Field.Root).
data-dirty	-	Present when the checkbox's value has changed (when wrapped in Field.Root).
data-touched	-	Present when the checkbox has been touched (when wrapped in Field.Root).
data-filled	-	Present when the checkbox is checked (when wrapped in Field.Root).
data-focused	-	Present when the checkbox is focused (when wrapped in Field.Root).
data-indeterminate	-	Present when the checkbox is in an indeterminate state.

CheckboxField

Takes every Checkbox prop except aria-label, aria-labelledby, and nativeButton.

Prop	Type	Description
`label`	`string`	Required. Names the checkbox.
`description`	`string`	Secondary line under the label.
`className`, `style`, `xstyle`	see Theming	Apply to the row, not the box.

Accessibility

The root carries role="checkbox" and aria-checked, which is "mixed" while indeterminate. Space toggles it.
A hidden <input type="checkbox"> beside it takes part in form submission.
CheckboxField renders a <label>. Its label text names the checkbox through aria-labelledby, and description is added to aria-describedby.
Keyboard focus shows the focus ring.