Checkbox

The <Checkbox> component is a form element that allows users to make a binary choice, either selecting or deselecting an option. Multiple checkboxes can be grouped together using <Checkbox.Group> to enable the selection of zero, one or any number of options.

It is commonly used in forms, settings, and anywhere users need to make multiple selections or toggle individual options. A <Checkbox> can also display an indeterminate state to represent a partially selected group.

Anatomy

A checkbox consists of a clickable box and a label. The box has three states: unchecked, checked, or indeterminate. The label, positioned next to the checkbox, describes the option or action associated with it. Users interact with the checkbox by clicking the box or label to toggle between states.

A checkbox group consists of multiple checkboxes, each with its own label, allowing users to select one or more options within a related set.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Variant

Size

The selected theme does not has any options for "variant" and "size".

I agree to the Terms of Service and Privacy Policy

Property	Type	Description
`variant`	`-`	The available variants of this component.
`size`	`-`	The available sizes of this component.

Usage

Checkboxes are used when there are multiple items to select in a list. Each checkbox works independently from other checkboxes in the list, therefore checking an additional box does not affect any other selections. Users can select zero, one, or any number of items. Checkboxes are commonly used in forms where users need to make multiple selections from a set of options.

Particularly checkboxes are useful in settings where users need to make non-exclusive selections. They provide a clear and straightforward way to toggle options on or off. When used in a group, they can help simplify complex decision-making processes. Additionally, checkboxes can be combined with other form elements.

Number of options

Use checkboxes when there are no more than 10 to 15 options, as too many of them can overwhelm users and clutter the interface. For larger sets of options, refer to the Multiple Selection Pattern for a better user experience.

If a user can select only one option from a list, radio buttons should be used instead, as checkboxes suggest that multiple options can be chosen.

Use checkboxes when you have up to 15 options, and multiple options can be chosen.

Don't

Don't use checkboxes when only one item can be selected.

Label Text

We recommend checkbox labels being fewer than three words because shorter checkbox labels improve readability and reduce cognitive load, making it easier for users to quickly understand and select options. This enhances the overall user experience, especially on small screens.

If you are tight on space, consider rewording the label. Do not truncate checkbox label text with an ellipsis. Long labels may wrap to a second line, and this is preferable to truncation.

If the label is long, wrap to a second line.

Don't

Do not truncate checkbox label text with an ellipsis.

Checkbox or switch

Use a checkbox when its effect will only occur after the user submits or confirms the selection. Checkboxes are ideal for allowing users to choose options that need to be finalized through submission, such as in a form.

In contrast, use a switch for actions that take effect immediately upon toggling, without requiring further confirmation or submission, making switches more suitable for instant settings changes.

Use checkboxes in forms where the selection will only take effect upon submission.

Don't

Don't use a checkbox to toggle a state with immediate effect.

Indeterminate

The indeterminate state of a checkbox is used when a group of related checkboxes is partially selected, meaning some but not all options are chosen. This state visually indicates that the selection is incomplete or mixed.

It’s commonly used in "Select All" scenarios, where selecting only some of the available options triggers the parent checkbox to show an indeterminate state, helping users understand that not all choices have been selected.

Props

Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!

View Checkbox stories

Checkbox

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 (or elements) that provide a detailed, extended description for the object.

aria-errormessage?

string;

Identifies the element that provides an error message for the object.

aria-label?

string;

Defines a string value that labels the current element.

aria-labelledby?

string;

Identifies the element (or elements) that labels the current element.

autoFocus?

boolean;

Whether the element should receive focus on render.

checked?

boolean;

Whether the element should be checked (controlled).

defaultChecked?

boolean;

Whether the element should be checked (uncontrolled).

disabled?

boolean;

Whether the checkbox is disabled.

Defaults to:

"false"

error?

boolean;

If true, the checkbox is considered invalid and if set the errorMessage is shown instead of the description.

Defaults to:

"false"

excludeFromTabOrder?

boolean;

Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.

id?

string;

The element's unique identifier. See MDN.

indeterminate?

boolean;

Use when it represents both selected and not selected values.

Defaults to:

"false"

inputRef?

RefObject<HTMLInputElement | null>;

A ref for the HTML input element.

label?

ReactNode;

Set the label of the checkbox.

name?

string;

The name of the input element, used when submitting an HTML form. See MDN.

onBlur?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element loses focus.

onChange?

(isSelected: boolean) => void;

Handler that is called when the element's selection state changes.

onFocus?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element receives focus.

onFocusChange?

(isFocused: boolean) => void;

Handler that is called when the element's focus status changes.

onHoverChange?

(isHovering: boolean) => void;

Handler that is called when the hover state changes.

onHoverEnd?

(e: HoverEvent) => void;

Handler that is called when a hover interaction ends.

onHoverStart?

(e: HoverEvent) => void;

Handler that is called when a hover interaction starts.

onKeyDown?

(e: KeyboardEvent) => void;

Handler that is called when a key is pressed.

onKeyUp?

(e: KeyboardEvent) => void;

Handler that is called when a key is released.

readOnly?

boolean;

Whether the checkbox is read-only.

Defaults to:

"false"

ref?

Ref<HTMLLabelElement>;

Allows getting a ref to the component instance. Once the component unmounts, React will set ref.current to null (or call the ref with null if you passed a callback ref). @see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}

required?

boolean;

Whether the checkbox is required.

Defaults to:

"false"

slot?

string | null;

A slot name for the component. Slots allow the component to receive props from a parent component. An explicit null value indicates that the local props completely override all props received from a parent.

validate?

(value: boolean) => true | ValidationError | null;

A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if validationBehavior="native". For realtime validation, use the isInvalid prop instead.

validationBehavior?

"native" | "aria";

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to:

'native'

value?

string;

The value of the input element, used when submitting an HTML form. See MDN.

Checkbox.Group

aria-describedby?

string;

Identifies the element (or elements) that describes the object.

aria-details?

string;

Identifies the element (or elements) that provide a detailed, extended description for the object.

aria-errormessage?

string;

Identifies the element that provides an error message for the object.

aria-label?

string;

Defines a string value that labels the current element.

aria-labelledby?

string;

Identifies the element (or elements) that labels the current element.

children?

ReactNode;

The children of the component

defaultValue?

string[]

The default value (uncontrolled).

description?

ReactNode;

A helpful text.

disabled?

boolean;

Sets all checkboxes to disabled

Defaults to:

"false"

error?

boolean;

If true, the checkbox is considered invalid and if set the errorMessage is shown instead of the description.

Defaults to:

"false"

errorMessage?

ReactNode | ((v: ValidationResult) => ReactNode);

An error message.

id?

string;

The element's unique identifier. See MDN.

label?

ReactNode;

Specifies the label of the field.

name?

string;

The name of the input element, used when submitting an HTML form. See MDN.

onBlur?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element loses focus.

onChange?

(value: string[]) => void;

Handler that is called when the value changes.

onFocus?

(e: FocusEvent<Element, Element>) => void;

Handler that is called when the element receives focus.

onFocusChange?

(isFocused: boolean) => void;

Handler that is called when the element's focus status changes.

orientation?

AlignmentProp;

Wheather the component is displayed vertically or horizontally.

Defaults to:

"vertical"

readOnly?

boolean;

Sets the checkbox on read only.

Defaults to:

"false"

required?

boolean;

Sets the checkbox as required.

Defaults to:

"false"

slot?

string | null;

validate?

(value: string[]) => true | ValidationError | null;

validationBehavior?

"native" | "aria";

Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA.

Defaults to:

'native'

value?

string[]

The current value (controlled).

width?

WidthProp;

Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width

Defaults to:

"full"

Alternative components

Choosing the right alternative to checkbox is important for providing an optimal user experience, especially when different types of selections are required. Depending on the nature of the choices and the desired interaction, the following components can serve as an alternative to checkboxes:

Switch: When there is only on option that should have an immediate effect.
Radio: When only one option can be selected from a set, a radio group is an alternative to a checkbox group, as radio buttons restrict the selection to a single option.
SelectList: When you need more than just a text label to represent options, a <SelectList> can be used instead.
TagGroup: When you want to visually highlight selected options as individual tags or want a horizontal list of options, use the <Tag> component.

Building forms

Learn how to build forms.

Multiple Selection

represents different ways and guideline for muliple selection.

Last update: 7 minutes ago