Checkbox

Tier: client

ImportCopy Anchor Link

import { Checkbox } from '@nizivo/react/checkbox';

// Once per app (Getting started), after
// @nizivo/tokens/tokens.css and @nizivo/react/css/base.css
import '@nizivo/react/css/checkbox.css';

Static or interactiveCopy Anchor Link

Client. It always ships its client leaf, which wires it to a Field and sets indeterminate (a DOM property with no attribute), and inside a Field also FieldScope. The server HTML is a native checkbox, so it toggles and submits before hydration. How to choose.

ExamplesCopy Anchor Link

import type { JSX } from 'react';
import { Checkbox } from '@nizivo/react/checkbox';

export function CheckboxExample(): JSX.Element {
  return (
    <Checkbox name="track-inventory" defaultChecked>
      Track inventory
    </Checkbox>
  );
}

import type { JSX } from 'react';
import { Stack } from '@nizivo/react/stack';
import { Checkbox } from '@nizivo/react/checkbox';

export function CheckboxStatesExample(): JSX.Element {
  return (
    <Stack gap="3">
      <Checkbox name="states" value="unchecked">
        Unchecked
      </Checkbox>
      <Checkbox name="states" value="checked" defaultChecked>
        Checked
      </Checkbox>
      <Checkbox name="states" value="mixed" defaultChecked="indeterminate">
        Some variants selected
      </Checkbox>
      <Checkbox name="states" value="disabled" disabled>
        Disabled
      </Checkbox>
      <Checkbox name="states" value="disabled-checked" disabled defaultChecked>
        Disabled and checked
      </Checkbox>
      <Checkbox name="states" value="invalid" invalid>
        Invalid
      </Checkbox>
    </Stack>
  );
}

import type { JSX } from 'react';
import { Fieldset } from '@nizivo/react/fieldset';
import { Checkbox } from '@nizivo/react/checkbox';

export function CheckboxGroupExample(): JSX.Element {
  return (
    <Fieldset legend="Notify me about" description="Emails go to the store owner.">
      <Checkbox name="notify" value="orders" defaultChecked>
        New orders
      </Checkbox>
      <Checkbox name="notify" value="stock">
        Low stock
      </Checkbox>
      <Checkbox name="notify" value="payouts" disabled>
        Payouts (needs a payment provider)
      </Checkbox>
    </Fieldset>
  );
}

import type { JSX } from 'react';
import { Field } from '@nizivo/react/field';
import { Checkbox } from '@nizivo/react/checkbox';

export function CheckboxFieldExample(): JSX.Element {
  return (
    <Field
      label="Terms of sale"
      description="Shown to buyers at checkout."
      error="Accept the terms to publish."
      required
    >
      <Checkbox name="terms">I accept the terms</Checkbox>
    </Field>
  );
}

PropsCopy Anchor Link

Other exportsCopy Anchor Link

CheckboxChangeReason type

import type { CheckboxChangeReason } from '@nizivo/react/checkbox'

Every change comes from the native change event: a click, Space, or a click on the label.

type CheckboxChangeReason = "input"

CheckboxCheckedState type

import type { CheckboxCheckedState } from '@nizivo/react/checkbox'

'indeterminate' is the mixed state of a "select all" box; it submits as unchecked.

type CheckboxCheckedState = boolean | "indeterminate"

CheckboxProps type

import type { CheckboxProps } from '@nizivo/react/checkbox'

The props of Checkbox, listed above.

CheckboxState type

import type { CheckboxState } from '@nizivo/react/checkbox'

What a render function receives for the root <label>.

The render state of Checkbox, listed above.

Data attributes and slotsCopy Anchor Link

Style parts by class (.nz-<slot>) and state by data attribute. Attribute meanings come from contracts/vocabulary.json.

CSS hooksCopy Anchor Link

Set a hook on the component's class or any ancestor to restyle it without specificity games; leave it unset for the default shown.

Layers: nz.components. Classes: .nz-checkbox, .nz-checkbox-indicator, .nz-checkbox-input, .nz-checkbox-label, .nz-glyph-check, .nz-glyph-minus.

AccessibilityCopy Anchor Link

These parts are interactive. Each gets the focus outline and touch-action rule from @nizivo/react/css/base.css (the nz.base layer), so the floor survives a restyle:

• checkbox-input: draws the focus outline itself on keyboard focus.

In forced-colours mode these states keep a visible system colour: checkbox-input (border), checkbox-input:checked (fill), checkbox-input:indeterminate (fill).

Pattern: WAI-ARIA Authoring Practices.

KeyboardCopy Anchor Link

Source: a native <input type="checkbox"> (checkbox.client.tsx), which adds no key handling; the browser lane (test/browser/toggles.spec.tsx) checks the mixed state and form data.

FigmaCopy Anchor Link

Node ids from design/component-map.json, which nz gen writes from component.json. The links open the Nizivo Figma library, which may ask you to sign in.

• Canonical: Figma node 7275:11456
• Ghost masters: Figma node 745:284