Checkbox

01Preview

Change the controls to try every supported combination. The preview is a real, controlled Checkbox: click it and the value control follows, and the code updates with it.

import { Checkbox } from '@nuton/ui'

const [checked, setChecked] = useState(true)

<Checkbox
  label="Email me when a student finishes a lesson"
  description="We send one summary a day, not one email per student."
  checked={checked}
  onCheckedChange={setChecked}
/>

02Installation

1. Add the packages

pnpm add @nuton/ui @nuton/tokens @remixicon/react

npm install @nuton/ui @nuton/tokens @remixicon/react

yarn add @nuton/ui @nuton/tokens @remixicon/react

Peer dependencies: react and react-dom 18 or later. @remixicon/react draws the check mark (Remix Icon is Nuton's icon set, D1).

2. Load tokens and component styles once

// app/layout.tsx (or your app's entry file)
import '@nuton/tokens/tokens.css' // --nu-* design tokens
import '@nuton/ui/styles.css'     // component styles (uses the tokens)

Labels use --nu-font-body (Inter). Map the token to your loaded font as described on the Button page. Checkbox is a client component ('use client'), so it works in server-rendered pages without extra setup.

03Usage

import { useState } from 'react'
import { Checkbox } from '@nuton/ui'

export function LessonReminders() {
  const [remind, setRemind] = useState(true)
  return (
    <Checkbox
      label="Remind students before a lesson is due"
      checked={remind}
      onCheckedChange={setRemind}
    />
  )
}

• Checkbox renders a native <input type="checkbox">, so forms, name/value, required and Space work without extra code.
• Use onCheckedChange for the new boolean. onChange still fires with the native event if you need it.
• Give every checkbox a name: label (preferred), a surrounding Field, or aria-label. A development warning flags a missing name.
• Write labels as a positive statement in sentence case: “Email me a weekly summary”, not “Don't email me”.
• Each checkbox is independent. When only one option may be chosen, use Radio.

04Variants and sizes

Checkbox has one size. Its variations are the value (unchecked, checked or indeterminate) and the optional text around the control, which follows Figma's Checkbox Label.

Value

<Checkbox aria-label="Unchecked" />
<Checkbox aria-label="Checked" defaultChecked />
<Checkbox aria-label="Indeterminate" indeterminate />

indeterminate is visual: it sets the native indeterminate property, so assistive technology announces “mixed”, but the submitted value still follows checked. Clicking clears it, so control it from state (see Select all lessons).

Label options

<Checkbox label="Show answers after the quiz" />
<Checkbox label="Allow late submissions" sublabel="(Optional)" />
<Checkbox
  label="Share progress with parents"
  description="Parents see completed lessons and quiz scores, not messages."
/>
<Checkbox
  label="Generate practice questions"
  badge={<Badge size="sm" color="blue" appearance="light">New</Badge>}
  action={<LinkButton href="/help/practice-questions" tone="primary" size="sm">How it works</LinkButton>}
/>
<Checkbox label="Notify me about new students" flip />

• sublabel sits inside the <label>, so it is part of the accessible name. It has no default text: pass a translated string. It is spaced with a margin, not a space character, so some browsers may join it to the label in the computed name (pending a decision).
• description is a second line linked with aria-describedby.
• badge and action render outside the <label>, so they aren't part of the name and the action is never nested in it.
• flip moves the control to the trailing edge, for settings lists where the text leads.

Sizes

Values from the component CSS, which follows Figma's geometry (Checkbox [1.1] 427:24777, Checkbox Label [1.1] 427:24813). Figma has one size only.

05States and interactions

State tokens

Set on .nu-checkbox. Override them on a wrapper only for a documented exception.

06Composition examples

Select all lessons

A parent checkbox summarises a list. It is checked when every lesson is selected, unchecked when none is, and indeterminate in between. Checking it selects all; unchecking it clears all. Try it, then add the selection to a space.

const [selected, setSelected] = useState<string[]>(['cells'])
const all = selected.length === lessons.length
const some = selected.length > 0 && !all

<Checkbox
  label="Select all lessons"
  checked={all}
  indeterminate={some}
  onCheckedChange={(checked) => setSelected(checked ? lessons.map((l) => l.id) : [])}
  aria-controls="lesson-list"
/>
<Button size="sm" onClick={addToSpace}>Add to space</Button>

<ul id="lesson-list" aria-label="Lessons">
  {lessons.map((l) => (
    <li key={l.id}>
      <Checkbox
        label={l.title}
        description={l.meta}
        checked={selected.includes(l.id)}
        onCheckedChange={(checked) =>
          setSelected((s) => (checked ? [...s, l.id] : s.filter((id) => id !== l.id)))
        }
      />
    </li>
  ))}
</ul>

Required agreement

Validate on submit, not on load. When the box is still unchecked, set invalid, put the reason in the description (it is linked with aria-describedby) and move focus to the checkbox.

<form onSubmit={join} noValidate>
  <Checkbox
    id="space-guidelines"
    label="I agree to the space guidelines"
    description={error
      ? 'Agree to the guidelines to join this space.'
      : 'Be kind, keep answers your own, and credit your sources.'}
    required
    invalid={error}
    checked={agreed}
    onCheckedChange={setAgreed}
  />
  <Button size="sm" type="submit">Join space</Button>
</form>

The description keeps the Sub-600 colour when invalid; only the frame turns red. Use the error colour for the message by wrapping the control in a Field instead (below).

Inside a Field

A Field names a single checkbox with its label and links its hint and error. Leave out the checkbox's own label, or it would be named twice.

<Field
  label="Publish to the space library"
  hint="Other teachers in Biology 101 can copy this lesson."
>
  <Checkbox defaultChecked />
</Field>

Groups of checkboxes

There is no checkbox group component. For a set of related options, wrap them in a <fieldset> with a <legend>, or an element with role="group" and aria-labelledby, so the question is announced with each option.

<div role="group" aria-labelledby="notify-heading">
  <span id="notify-heading">Send me an email when</span>
  <Checkbox name="notify" value="joined" label="A student joins the space" defaultChecked />
  <Checkbox name="notify" value="finished" label="A student finishes a lesson" />
  <Checkbox name="notify" value="question" label="A student asks the AI tutor for help" defaultChecked />
</div>

07API reference

Props

Styling hooks

The control renders .nu-checkbox (with data-invalid and data-disabled) around .nu-checkbox__input and .nu-checkbox__box. With a label, the layout is .nu-choice with data-kind="checkbox", data-flip, data-disabled and data-has-description, shared with Radio. Use props rather than styling these; the --nu-checkbox-* tokens (see State tokens) are the supported override points.

Accessibility

You must: give every checkbox a name (label, a Field or aria-label); control indeterminate from state; say why an unchecked required checkbox is invalid in text, not only with the red frame; group related checkboxes under a legend or a labelled group.

Figma mapping

08Guidelines and related components

Do and don't

Common mistakes

• Setting indeterminate once and never updating it. A click clears the native property; drive it from state on every render.
• Putting a link inside label. Clicking it toggles the box. Use action instead.
• Giving a checkbox in a Field its own label too, so it is announced twice.
• Relying on the red frame alone for an error. It only shows while unchecked and has no text.

Related components

• RadioPick exactly one option from a group.
• Inputs and fieldsLabel, hint and error wiring for a single checkbox.
• Dropdown menuCheckbox items inside a menu.
• BadgeThe badge passed to a checkbox label.
• Link buttonThe action under a checkbox label.