All components (204)

Checkbox

Choice · Checkbox · .amset-checkbox

What it is and when to use it

A checkbox: yes or no on one thing, or ticking several from a list. It is pressed anywhere on the label, not just on the square.

When to use it

Accepting something that is sent with a button: "I accept the terms of sale". The change counts when Submit is pressed, not before.
Ticking several options from a short list. With indeterminate, the "Select all" checkbox when only some are ticked.
In a table row, with no text next to it: the name then goes in aria-label. The types do not allow a mute checkbox to be built.

When not to

A setting that is applied right away, without Save: Switch.
One option among several that exclude each other: RadioGroup, or SegmentedGroup if the change is seen instantly.
The facets of a catalog, with a counter and "Show the remaining N": FilterGroup.

Keyboard: Tab reaches it; Space ticks and unticks it. When disabled it leaves the Tab order.

Accessibility: it is a real <input type="checkbox">, hidden under the square that is seen, and its name is the text. With name and value it travels in a native form. The description is read as a description, after the name: it is not part of it. The indeterminate state is announced as "partially checked", not only with the dash. The tick and the dash in the square are decorative.

Sizes: 14, 16 or 20 px box, centered on the first line of the text. With a finger, the row reaches 44 px; on its own (in a table), the pressable area grows outwards up to 24 px with a mouse and 44 with a finger, without moving anything.

States: hover, pressed (the box gives in a little), keyboard focus, checked or half-checked (the tick grows in), invalid, read-only (dashed border and no accent fill) and disabled.

Fine-tuning: variables --amset-checkbox-box, -radius, -font, -description, -border, -background, -checked (the fill when ticked) and -brand (the color of the tick).

What it looks like

I accept the termsEmail alerts

<Checkbox defaultSelected>I accept the terms</Checkbox>
<Checkbox description="You can unsubscribe whenever you want">Email alerts</Checkbox>

Props

Import it with import { Checkbox } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`aria-controls`	`string`	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-describedby`	`string`	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	Identifies the element that provides a detailed, extended description for the object.
`aria-labelledby`	`string`	Identifies the element (or elements) that labels the current element.
`autoFocus`	`boolean`	—
`children`	`ReactNode`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`defaultSelected`	`boolean`	Checked at the start, governed internally.
`description`	`string`	Secondary text under the label. The screen reader reads it as a description, after the name: it is not part of it. It is only painted if the checkbox has a visible label.
`disabled`	`boolean`	—
`excludeFromTabOrder`	`boolean`	Takes it out of the tab order without removing focus programmatically.
`form`	`string`	The `id` of the `<form>` it belongs to, if it is not wrapped by it.
`id`	`string`	Goes to the `<input>`, which is the focusable node.
`indeterminate`	`boolean`	The third face: neither checked nor unchecked. It is presentation only and does not change when pressed; it is for the checkbox that governs a half-selected list.
`inputRef`	`Ref<HTMLInputElement>`	To reach the real `<input>`.
`invalid`	`boolean`	—
`name`	`string`	The name it travels under in the form.
`onBlur`	`(event: FocusEvent<HTMLInputElement>) => void`	—
`onChange`	`(selected: boolean) => void`	—
`onChangeEvent`	`(event: ChangeEvent<HTMLInputElement>) => void`	Like `onChange`, but with the native event of the `<input>`: `e.target.checked`... It exists to migrate a front end that already writes its handlers with the event (AMS-735). If you only want to know whether it is checked, `onChange` already gives you that.
`onFocus`	`(event: FocusEvent<HTMLInputElement>) => void`	—
`onPress`	`(event: ChoicePressEvent) => void`	Called when it is pressed, saying what it was pressed with.
`readOnly`	`boolean`	It is read and focused, but does not change.
`required`	`boolean`	—
`selected`	`boolean`	Checked, governed from outside.
`size`	`"sm" \| "md" \| "lg"`	Size of the box and the text: box of 14, 16 or 20 px. With a finger, the row reaches 44 px.
`validationBehavior`	`ValidationBehavior`	`native` by default, as until now: it sets the browser's `required`.
`value`	`string`	Its key within a group of checkboxes, and the value it travels with in the form when checked.

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

CSS variables

These CSS variables are how you adapt it. Declare them on the component's selector, not on :root: the stylesheet redeclares them in the rule itself, and a declaration on the same element always wins.

Variable	Default
`--amset-checkbox-box`	`1rem`
`--amset-checkbox-radius`	`var(--amset-radius-sm)`
`--amset-checkbox-font`	`var(--amset-text-base)`
`--amset-checkbox-description`	`var(--amset-text-sm)`
`--amset-checkbox-border`	`var(--amset-border-bold)`
`--amset-checkbox-background`	`var(--amset-surface)`
`--amset-checkbox-checked`	`var(--amset-accent)`
`--amset-checkbox-brand`	`var(--amset-accent-ink)`
`--amset-checkbox-line`	`calc(var(--amset-checkbox-font) * var(--amset-line-tight))`
`--amset-checkbox-target`	`1.5rem`

How to change it

.amset-checkbox {
  --amset-checkbox-box: ...;
  --amset-checkbox-radius: ...;
}

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: