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.

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.

Labeling

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.

Do

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

Don't

Do not truncate checkbox label text with an ellipsis.

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.

Do

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.

When a checkbox list is long enough to create clutter, overload, or excessive scrolling, keep it compact while allowing access to all options. Show only the most relevant five to eight items initially, with the rest hidden until revealed, and use this approach sparingly when all items can be scanned easily. Use this method sparingly, avoiding its use when the total number of items can be quickly scanned without frustration.

import { Checkbox } from '@marigold/components';export default () => (  <Checkbox.Group collapseAt={5} defaultValue={['parking', 'seating']}>    <Checkbox value="parking" label="Parking" />    <Checkbox value="seating" label="Reserved Seating" />    <Checkbox value="drinks" label="All you can drink" />    <Checkbox value="food" label="Food Voucher" />    <Checkbox value="wifi" label="Wi-Fi Access" />    <Checkbox value="cloakroom" label="Cloakroom Service" />    <Checkbox value="merch" label="Merchandise Voucher" />    <Checkbox value="vip" label="VIP Access" />    <Checkbox value="meetgreet" label="Meet & Greet" />    <Checkbox value="photo" label="Photo Pass" />  </Checkbox.Group>);

Ordering of Options

Options should be arranged by relevance to help users find what they need quickly. Prioritizing by factors such as frequency of use, overall popularity, or recency of interaction ensures the most useful items appear first. Alphabetical order should be considered only when no meaningful ranking criteria are available, as it may not align with user priorities or usage patterns.

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.

Do

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.

import { useState } from 'react';import { Checkbox, Inset, Stack } from '@marigold/components';const genres = {  rock: 'Rock',  pop: 'Pop',  jazz: 'Jazz',  hiphop: 'Hip-Hop',  classical: 'Classical',  country: 'Country',  electronic: 'Electronic',  rnb: 'R&B',} as const;const size = Object.keys(genres).length;type Genres = keyof typeof genres;export default () => {  const [selected, setSelected] = useState<Genres[]>(['jazz', 'electronic']);  const allProps = {    indeterminate: selected.length > 0 && selected.length < size,    checked: selected.length === size,    onChange: () => {      // eslint-disable-next-line @typescript-eslint/no-unused-expressions      selected.length === size        ? setSelected([])        : setSelected(Object.keys(genres) as Genres[]);    },  };  return (    <Stack space={1}>      <Checkbox {...allProps}>All</Checkbox>      <Inset spaceX={4}>        <Checkbox.Group          aria-label="Favorite genres"          value={selected}          onChange={(keys: Genres[]) => setSelected(keys)}        >          {Object.entries(genres).map(([value, label]) => (            <Checkbox key={value} value={value} label={label} />          ))}        </Checkbox.Group>      </Inset>    </Stack>  );};

Description

Adding a description to a checkbox is helpful when the label alone isn't enough to explain its function. Use a description to clarify complex or ambiguous actions, such as when the checkbox triggers a permanent change or has significant consequences. It's also useful for explaining technical terms or jargon that might be unfamiliar to the user. Finally, include a description to provide important context or warnings, like legal disclaimers or potential costs, ensuring the user fully understands what they're agreeing to.

import { Checkbox } from '@marigold/components';export default () => (  <Checkbox    label="Enable SSL/TLS"    description="This encrypts the data transferred between your browser and our server."  />);

Props

Checkbox

Checkbox.Group

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.

Related