Checkbox

Checkboxes allow for selecting multiple options from a set.

Selected

Unselected

Mixed

Overview

Checkboxes are selection controls that allow users to select multiple options from a set. They appear as small squares that display a checkmark when selected. Checkboxes are independent of each other, meaning selecting one does not affect the others in the same group.

Usage

forge-checkbox selects one or more independent options through checked and indeterminate, participates natively in form submission and validation (required, readonly, name), and supports dense and label-position. Use a checkbox when a user can pick any number of options from a list; use a radio button instead when exactly one option in a set must be chosen, or a switch instead to toggle a single setting on or off.

Rules

Use checkboxes when a user can select zero, one, or many options from a list.

Pair every checkbox with a clear, clickable label — don't rely on the box alone.

Use the indeterminate state to reflect a parent checkbox whose children are partially selected.

Don't

Don't use a checkbox for a single on/off setting — use a switch instead.

Don't use a checkbox when only one option in a set can be selected — use a radio button instead.

Don't treat indeterminate as user-settable — it's a display-only state the app computes from the children's selection.

Indeterminate

Set checked and indeterminate to render distinct marks — indeterminate reflects a parent checkbox whose children are only partially selected.

Checked and indeterminate render distinct marks.

<forge-checkbox checked>
  Checked
</forge-checkbox>
<forge-checkbox indeterminate>
  Indeterminate
</forge-checkbox>

Label position

Set label-position to control whether the label sits before or after the checkbox.

label-position controls whether the label sits before or after the checkbox.

<forge-checkbox>
  End (default)
</forge-checkbox>
<forge-checkbox label-position="start">
  Start
</forge-checkbox>

Dense

Set dense to reduce the checkbox’s size for compact layouts.

Dense reduces the checkbox's size for compact layouts.

<forge-checkbox dense>
  Dense
</forge-checkbox>

Disabled and readonly

disabled excludes the checkbox from the form; readonly keeps it in the form but locks its value.

Disabled excludes the checkbox from the form; readonly keeps it in the form but locks its value.

<forge-checkbox disabled>
  Disabled
</forge-checkbox>
<forge-checkbox readonly checked>
  Readonly
</forge-checkbox>

Checkboxes select single values for submission in a form.

import "@tylertech/forge/checkbox";

Properties

Property	Attribute	Type	Default	Description
`checked`	`checked`	`boolean`	`false`	Gets/sets whether the checkbox is checked.
`defaultChecked`	`default-checked`	`boolean`	`false`	Gets/sets whether the checkbox is checked by default.
`indeterminate`	`indeterminate`	`boolean`	`false`	Gets/sets the indeterminate state.
`value`	`value`	`string`	`'on'`	Controls the value submitted with a form when checked.
`dense`	`dense`	`boolean`	`false`	Controls whether the checkbox is dense.
`disabled`	`disabled`	`boolean`	`false`	Controls whether the checkbox is disabled.
`required`	`required`	`boolean`	`false`	Controls whether the checkbox is required.
`readonly`	`readonly`	`boolean`	`false`	Controls whether the checkbox is readonly.
`labelPosition`	`label-position`	`CheckboxLabelPosition`	`'end'`	Controls whether the label appears before or after the checkbox.

Events

Name	Type	Description
`change`	`Event`	Dispatches when the checkbox is checked or unchecked.

CSS Parts

Name	Description
`::part(root)`	Styles the root element.
`::part(background)`	Styles the checkbox background element.
`::part(checkmark)`	Styles the checkmark element.
`::part(mixedmark)`	Styles the indeterminate mark element.
`::part(label)`	Styles the label element.
`::part(state-layer)`	Styles the state layer element.
`::part(focus-indicator)`	Styles the focus indicator element.

CSS Custom Properties

Name	Description
`--forge-checkbox-background`	The color of the checkbox background when unchecked and not indeterminate.
`--forge-checkbox-width`	The inline size of the checkbox.
`--forge-checkbox-height`	The block size of the checkbox.
`--forge-checkbox-unchecked-border-width`	The width of the checkbox border when unchecked and not indeterminate.
`--forge-checkbox-unchecked-border-color`	The color of the checkbox border when unchecked and not indeterminate.
`--forge-checkbox-shape`	The shape of the checkbox.
`--forge-checkbox-elevation`	The shadow of the checkbox.
`--forge-checkbox-gap`	The space between the checkbox and label.
`--forge-checkbox-justify`	How the checkbox and label are distributed along their main axis.
`--forge-checkbox-align`	How the checkbox and label are distributed along their cross axis.
`--forge-checkbox-direction`	Whether the checkbox and label are arranged along the inline or block axis.
`--forge-checkbox-checked-background`	The color of the checkbox background when checked or indeterminate.
`--forge-checkbox-checked-border-width`	The width of the checkbox border when checked or indeterminate.
`--forge-checkbox-checked-border-color`	The color of the checkbox border when checked or indeterminate.
`--forge-checkbox-icon-checked-color`	The color of the checkmark mark.
`--forge-checkbox-icon-indeterminate-color`	The color of the indeterminate mark.
`--forge-checkbox-icon-stroke-width`	The stroke width of the checkmark and indeterminate marks.
`--forge-checkbox-state-layer-width`	The inline size of the state layer.
`--forge-checkbox-state-layer-height`	The block size of the state layer.
`--forge-checkbox-state-layer-checked-color`	The color of the state layer when checked.
`--forge-checkbox-state-layer-unchecked-color`	The color of the state layer when unchecked.
`--forge-checkbox-state-layer-shape`	The shape of the state layer.
`--forge-checkbox-state-layer-dense-width`	The inline size of the state layer when dense.
`--forge-checkbox-state-layer-dense-height`	The block size of the state layer when dense.
`--forge-checkbox-disabled-opacity`	The opacity when disabled.
`--forge-checkbox-animation-duration`	The duration of animations.
`--forge-checkbox-background-animation-timing`	The timing function of the background animations.
`--forge-checkbox-icon-animation-timing`	The timing function of the checked and indeterminate icons animations.

Methods

Name	Returns	Description
`toggle(force)`	`void`	Toggles the checkbox checked or unchecked.

Keyboard interaction

Every checkbox must be reachable by Tab, and pressing Space while focused toggles it the same as a mouse click.

Visual states

Checked, unchecked, focused, and disabled each need a distinct, visible cue — not just a color change.