Checkbox

import { ... } from '@ag.ds-next/react/checkbox';

<Checkbox value="basic-checkbox">Basic checkbox</Checkbox>

Do

• use to help users to select one or more options
• use for a short list of options
• use the Control group component to group multiple related checkboxes
• ensure users can select multiple related checkboxes at a time
• use a vertical list of options when grouping multiple related checkboxes

Don’t

• provide disabled options unless unavoidable
• use a horizontal list of options when grouping multiple related checkboxes unless unavoidable.

Grouping checkboxes

Use the Control group component to group multiple related checkboxes.

<ControlGroup label="Example" block>
	<Checkbox value="phone">Phone</Checkbox>
	<Checkbox value="tablet">Tablet</Checkbox>
	<Checkbox value="tablet">Laptop</Checkbox>
</ControlGroup>

Hint

Use the hint prop to provide help that’s relevant to the majority of users, like how their information will be used, or where to find it.

Don’t use long paragraphs and lists in hint text. Screen readers read out the entire text when users interact with the form element. This could frustrate users if the text is long.

Don’t include links within hint text. While screen readers will read out the link text when describing the field, they will not tell users that the text is a link.

<ControlGroup label="Example" hint="Hint text" block>
	<Checkbox value="phone">Phone</Checkbox>
	<Checkbox value="tablet">Tablet</Checkbox>
	<Checkbox value="laptop">Laptop</Checkbox>
</ControlGroup>

Invalid

Use the invalid prop to indicate if the user input is invalid.

<ControlGroup
	label="Invalid example"
	message="Please choose an option"
	invalid
	block
>
	<Checkbox>Phone</Checkbox>
	<Checkbox>Tablet</Checkbox>
	<Checkbox>Laptop</Checkbox>
</ControlGroup>

Required

The required prop can be used to indicate that user input is required on the field before a form can be submitted.

Required fields do not append ‘(optional)’ to the label and also use aria-required to indicate to screen readers that the field is required.

Hide optional label

The hideOptionalLabel prop can be used in situations where you want to indicate to screen reader users that a field is optional but don’t want to show the ‘(optional)’ label.

The usage of hideOptionalLabel should be reserved for inputs that filter data in a table or chart, and should never be used in standard forms for submitting information.

<Stack gap={1}>
	<ControlGroup label="Required" required block>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
	<ControlGroup label="Optional" required={false} block>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
	<ControlGroup
		label="Optional with hideOptionalLabel"
		required={false}
		hideOptionalLabel={true}
		block
	>
		<Checkbox value="phone">Phone</Checkbox>
	</ControlGroup>
</Stack>

Disabled

Disabled checkboxes can be used to indicate inputs that are no longer valid or expired.

<Stack gap={1}>
	<Checkbox value="phone" disabled>
		Disabled checkbox
	</Checkbox>
	<Checkbox value="tablet" checked disabled>
		Disabled and checked checkbox
	</Checkbox>
	<Checkbox value="laptop" indeterminate disabled>
		Disabled and indeterminate checkbox
	</Checkbox>
</Stack>

Indeterminate

A indeterminate checkbox is used to represent a group of checkboxes that has a mix of selected and unselected values.

When a checkbox is indeterminate, it overrides the checked state.

<Checkbox indeterminate>Indeterminate</Checkbox>

Small

Use the size prop to change the size of the checkbox.

<Stack gap={1}>
	<Checkbox size="sm" value="small">
		Small checkbox
	</Checkbox>
	<Checkbox size="md" value="phone">
		Medium checkbox (default)
	</Checkbox>
</Stack>

Related components

• Control group – Control groups allow related checkboxes and radios to be grouped together.
• Radio – Radios allow users to select one option from a list.
• Switch – A Switch allows a user to immediately toggle interface settings.

Related patterns

• Conditionally revealed content – Conditionally reveal a question or information related to a specific radio or checkbox option when a user selects it. This ensures that users only encounter conditionally revealed content when it is applicable to their selection.
• Selecting multiple options – Multi-select is a commonly used design pattern that allows users to select multiple options from a list. This pattern is used in various contexts such as search filters, form fields, and more.