> ## Documentation Index
> Fetch the complete documentation index at: https://invoca-5bd45748-mintlify-6c3474a6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkbox

> An independent on/off choice, or one row in a multi-select list. Checking one Checkbox never affects another's state.

export const StorybookFrame = ({story, height = 200, viewMode = "story", globals = null, title}) => {
  const STORYBOOK_ORIGIN = "https://main--64e4dc66838839c721332d22.chromatic.com";
  const parts = [`id=${story}`, `viewMode=${viewMode}`, "shortcuts=false"];
  if (viewMode === "story") parts.push("singleStory=true");
  if (globals) {
    const g = Object.keys(globals).map(k => `${k}:${globals[k]}`).join(";");
    parts.push(`globals=${g}`);
  }
  const src = `${STORYBOOK_ORIGIN}/iframe.html?${parts.join("&")}`;
  const canonical = `${STORYBOOK_ORIGIN}/index.html?path=/${viewMode === "docs" ? "docs" : "story"}/${story}`;
  return <div className="my-4 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-800">
      <iframe src={src} title={title || `Titan Storybook: ${story}`} loading="lazy" style={{
    width: "100%",
    height: `${height}px`,
    border: "0",
    display: "block"
  }} />
      <div className="flex items-center justify-between border-t border-gray-200 bg-gray-50 px-3 py-2 text-xs dark:border-gray-800 dark:bg-gray-900">
        <span className="font-mono text-gray-500 dark:text-gray-400">{story}</span>
        <a href={canonical} target="_blank" rel="noreferrer" className="text-gray-500 underline dark:text-gray-400">
          Open in Storybook ↗
        </a>
      </div>
    </div>;
};

## What it is

A control for an independent binary choice, checked or not, that also stands as one row in a
multi-select list. Checking a Checkbox never unchecks another one — that exclusivity is what
separates it from [Radio](/invoca-design-system/components/forms/radio).

## Live example

<StorybookFrame story="components-form-elements-checkboxes--checkbox-input" height={120} />

## Exports

<Snippet file="generated/props/checkbox.mdx" />

## Vocabulary

| Term           | Also called                      | The system uses         |
| -------------- | -------------------------------- | ----------------------- |
| **Select-all** | Header checkbox, master checkbox | **Select-all checkbox** |

The design library's Checkbox has no indeterminate state at all — see
[Open issues](/invoca-design-system/components/forms/checkbox/open-issues) for how that was
verified and an earlier correction to this page.

<Info>
  **The bare box and the labeled composite name the same property differently.** The
  standalone `Checkbox` component's boolean property is `Checked`; the `Checkbox + Label`
  composite's equivalent property is `Selected`. [Radio](/invoca-design-system/components/forms/radio) does not
  have this split — both its bare control and its labeled composite use `Selected`.
</Info>

## Choose Checkbox when

* The choice is independent — selecting it does not exclude any other option.
* Zero, one, or many of a set of options may be true at once, including all or none.

## Choose something else when

| If you need to…                                                    | Use                                                                                        | Why                                                                                                                                    |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| Offer exactly one of several mutually exclusive options            | Radio                                                                                      | A group of Checkboxes communicates independence; enforcing "only one" on top of that fights what the control tells the reader it means |
| Capture a single, standalone setting that takes effect immediately | Switch                                                                                     | Switch communicates immediate effect; Checkbox implies part of a form the reader still has to submit                                   |
| Choose among many options in a long, searchable list               | [Select](/invoca-design-system/components/forms/select) (multiple), with `Autocomplete` on | Forty Checkboxes in a list is a scroll problem a searchable, filterable control removes                                                |

## Anatomy

| # | Part          | Required                                           |
| - | ------------- | -------------------------------------------------- |
| 1 | Box           | Yes                                                |
| 2 | Control label | No — see [TITAN-CHK-02](#constraints) when omitted |

<Info>
  **No indeterminate marker exists in the design library.** See
  [Vocabulary](#vocabulary).
</Info>

## Variants, sizes, and states

<Snippet file="generated/matrix/checkbox.mdx" />

## Edge and failure states

| Situation                                               | What renders                                                                     | Recovery                                                                                          |
| ------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| No visible label (e.g., a table row-selection checkbox) | The box alone                                                                    | Must still carry an explicit accessible name — see [TITAN-CHK-02](#constraints)                   |
| A select-all checkbox whose group is partially checked  | **Undefined.** No mixed or indeterminate rendering exists in the design library. | See [TITAN-GAP-33](/invoca-design-system/foundations/open-decisions#titan-gap-33)                 |
| Disabled and checked                                    | Renders at the disabled opacity applied over the checked fill                    | No dedicated disabled-checked colour exists as its own token — the two compose                    |
| A group with zero items                                 | **Undefined** whether the select-all control hides or disables itself            | See [Gaps](/invoca-design-system/components/forms/checkbox/open-issues#gaps-in-the-current-rules) |

## Tokens

<Snippet file="generated/tokens/checkbox.mdx" />

## Composition

Pairs with a control label immediately trailing it (LTR) — see
[FieldLabel's control-label vocabulary](/invoca-design-system/components/forms/field-label#vocabulary). A group of
related Checkboxes is exposed as a set with its own group name, distinct from any individual
option's label — see [TITAN-CHK-05](#constraints). A select-all checkbox sits at the head of
the list it controls.

For a complete field rather than the bare control, compose through `FormInput` with
`type="checkbox"` — see [TITAN-CHK-07](#constraints).

## Content

| Rule                                                         | ✅                   | ❌                                                       |
| ------------------------------------------------------------ | ------------------- | ------------------------------------------------------- |
| Each option label is a noun phrase, not a question           | Email notifications | Do you want email notifications?                        |
| Select-all is labeled distinctly from any option it controls | "Select all"        | A control labeled identically to one of its own options |

## Accessibility

| Key              | Behavior                    |
| ---------------- | --------------------------- |
| <kbd>Tab</kbd>   | Moves focus to the Checkbox |
| <kbd>Space</kbd> | Toggles checked             |

* Renders a native `<input type="checkbox">`.
* A group of related Checkboxes is announced as a set (a fieldset with a legend, or the
  equivalent grouping role), separately from any one option's own label.
* A Checkbox with no visible label — a table row selector, most often — carries an explicit
  accessible name describing what it selects, such as "Select row: Acme Corp," not a generic
  "Checkbox."

**What this component does not handle:** deciding whether a selection is valid or required —
that belongs to [Form validation](/invoca-design-system/patterns/form-validation).

## Constraints

| ID               | Constraint                                                                                                                                                                                                                                                                        | Rationale                                                                                                                                                                                                               |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **TITAN-CHK-01** | Checkbox expresses an independent choice. Use Radio when only one of several options may be true.                                                                                                                                                                                 | Mixing the two vocabularies — independent controls that behave exclusively — reads as a bug to anyone who has used either correctly elsewhere.                                                                          |
| **TITAN-CHK-02** | A Checkbox with no visible label carries an explicit accessible name describing what it selects.                                                                                                                                                                                  | Without one, a screen reader announces "checkbox" and nothing else — indistinguishable from every other unlabeled checkbox on the page.                                                                                 |
| **TITAN-CHK-04** | A disabled Checkbox is always accompanied by a reachable explanation of what would enable it.                                                                                                                                                                                     | Same reasoning as [TITAN-BTN-06](/invoca-design-system/components/actions/button#constraints).                                                                                                                          |
| **TITAN-CHK-05** | A group of related Checkboxes is exposed as a set with its own name, separate from any individual option's label.                                                                                                                                                                 | Without a group name, a reader navigating by label alone cannot tell that "Email" and "SMS" belong to the same "Notification channels" decision.                                                                        |
| **TITAN-CHK-07** | A complete field — label, helper text, and error state together — is composed via [Form](/invoca-design-system/components/forms/form)'s `FormInput` with `type="checkbox"` (single, or with `options` for a group), never by hand-assembling a raw Checkbox and FormControlLabel. | Source publishes `DoNotUse_RawCheckbox` as a named anti-pattern story, stating directly that the raw combination skips batch select tools, standardized label/helper/error display, and token-matched disabled styling. |

<Note>
  **TITAN-CHK-03 and TITAN-CHK-06 are retired.** Both asserted rules about an indeterminate
  state that Figma evidence shows does not exist in the design library — see
  [Vocabulary](#vocabulary). Per this site's own convention, a missing number means a retired
  rule, not an error; the numbers are not reused.
</Note>

## Known issues

<Card title="Checkbox: open issues" icon="triangle-exclamation" href="/invoca-design-system/components/forms/checkbox/open-issues">
  Divergences, open decisions, and undocumented gaps for Checkbox.
</Card>

## Why it works this way

**Checkbox stays a strictly binary control** — the design library defines no third visual
state, so nothing about how it's built lets a select-all checkbox show "some, but not all" of
its group short of inventing a treatment that doesn't exist yet. See
[TITAN-GAP-33](/invoca-design-system/foundations/open-decisions#titan-gap-33) for what that leaves unresolved.

## Status

<Snippet file="generated/status/checkbox.mdx" />

## Related

<Snippet file="generated/utilization/checkbox.mdx" />

* [FieldLabel](/invoca-design-system/components/forms/field-label) — the control-label pairing every Checkbox uses
* [Select](/invoca-design-system/components/forms/select) — the searchable, long-list alternative
* [Bulk selection](/invoca-design-system/patterns/bulk-selection) — the pattern governing select-all and row selection in tables