Component Checkbox Group

Checkbox groups are used to group multiple checkboxes in a single form field that takes care of the label, help message, and error state. This component is used in conjunction with checkbox component.

Get the UI kit

Code

Usage

Example

Props

Attr	Type	Default	Docs
error	string	null	This property can be used to set an error. If a non-empty string is given, it will be used as the error message.
help	string	''	This property can be used to set a help text.
hide-label	boolean	false	This property will visually hide the label. A label is still required to be provided for screenreader support.
indeterminate	boolean	false	This property controls whether the checkbox is in an indeterminate state.
inline	boolean	false	This boolean sets whether the form field group should display the checkboxes inline or not.
label	string	''	This property can be used to set the inline label.
label-class	string	''	This property is a list of CSS classes that can be used to style the label.
required	boolean	false	This boolean sets whether the form field group is required or not.
required-ind	"none" \| "optional" \| "required"		This property is used to override the required indicator. By default, forms elements will show an `optional` indicator but some forms are better served showing the `required` indicator instead.
tooltip	string	null	This property is used to set the tooltip text.

Slots

Name	Docs
label	Label for the checkbox group. Alternatively, you can use the label attribute.

Anatomy

A visual depicting parts of the checkbox and the checkbox group, as described below.

Group label: Communicates what needs to be selected below.
Checkbox: A single available selection.
Checkbox input: Where the checkbox’s status is displayed.
Checkbox label: The label of the individual checkbox selection.
Helper text: Provides additional context if needed.
Checkbox group: A group of related selectable options.

Labels

Each field needs a label, which should be clear and concise. Don't include punctuation after checkbox labels.

A group label above a checkbox group, as described in the caption below.

A checkbox group lacking a group label, as described in the caption below.

Always use a group label when using multiple checkboxes.

Failing to add a group label can confuse users as to what the selections represent.

Custom labels

A label can be left out if a selection is obvious without it, such as a selectable row in a data table or if the checkbox is in a selectable card.

Checkboxes in a data table as described in the caption below. — The content of the data table row clarifies what the checkbox will select.

Helper text

Optional helper text contains pertinent information that assists the user in correctly completing a field. It is often used to explain the correct data format.
Use sentence-style capitalization, and in most cases, write the text as full sentences with punctuation to ensure the helper text is clear and easy to understand.
When using punctuation in one area, be sure to use it consistently in similar contexts.
When used, helper text appears below the field, except when an error or warning message replaces it.

Required and optional

Not every checkbox group requires a selection. There are ways to indicate that they’re optional.

When possible, don’t ask for unnecessary information. This prevents users from getting overwhelmed.
If most of the form’s fields are required, mark only the optional fields.
If most of the form’s fields are optional, mark only the required fields.

By default, fields not marked as required will show “(optional)” indicators. It's possible to manually override this behavior to display indicators for required fields instead. Visit the code section to learn more.

A checkbox group marked as required with a red asterisk next to a checkbox group marked as optional, as described in the content above. — Fields should be marked either optional or required if they are the outlier.

Tooltips

You can add a tooltip to an individual checkbox or a checkbox group by setting its tooltip attribute to the desired text. Use tooltips sparingly, and keep text brief and supplementary. Do not include interactive elements. The tooltip appears on hover or keyboard focus.

If you'd like to support our cat rescue, let us know how!

Foster

Adopt

Volunteer

Donate

How to use

Use a checkbox if:

A user needs to toggle between Boolean states.
A user needs to acknowledge or affirm something, such as agreeing to terms and conditions.

Use a checkbox group if:

A user can make any number of selections — zero, one, or many — from a list of options.
There is sufficient room to display all options at once.

Proper uses for checkboxes, as described in the caption below.

Use a checkbox group when a user can make multiple selections. Use a checkbox when there is a single option, such as agreeing to terms and conditions.

Checkbox or radio button?

Although checkboxes and radio buttons look similar, their use cases are different. If users can only pick one option from a list, use a radio button group instead.

A radio button group used to make a single selection, as described in the caption below.

Checkboxes used incorrectly, as described in the caption below.

Use radio buttons when only one option can be chosen.

Don’t use checkboxes when only one option can be selected.

Checkbox or toggle?

Checkboxes and toggles are often functionally interchangeable, but using the right one can have an impact on your users’ experience. Use a toggle instead if:

Users are activating, deactivating, or turning something on and off.
The use case is analogous to flipping a switch.
There's no wrong answer, and no possible way to make an error with a choice, or lack thereof.

A toggle used properly, as described in the caption below.

A checkbox used in a situation where a toggle would suffice, as described in the caption below.

Toggles are good for activating a setting.

Don’t use a checkbox for actions that need to be activated.

Behavior

States

There are multiple states for checkboxes. Users can select or unselect a checkbox in any state, save for the disabled state.

The default, hover, active, focus, and disabled checkbox states, as described in the caption below. — The checkbox changes states based on user interactions.

Default: The standard state of a checkbox.
Hover: When a user’s cursor moves over a checkbox without clicking it.
Active: When users press a checkbox without releasing.
Focus: When a user highlights a checkbox with a keyboard.
Disabled: An unavailable selection. Be sure that users aren’t confused as to why a checkbox is disabled. If the user is likely to be confused, keep it enabled and trigger a detailed error when it’s clicked or when the form is submitted.

Errors

Errors for checkboxes let users know that a required selection was left empty. Individual errors and checkbox group errors are two different error states.

An individual checkbox error occurs when a user fails to make a mandatory selection.
A group error occurs when users make an invalid selection, or no selection in a required field.
Make sure error text is helpful and concise.

An unchecked checkbox, a checked checkbox, and a checkbox group marked as an error, as described in the caption below. — When an error occurs in a selection or a selection is required, the checkbox turns red and red helper text appears below.

Text wrapping

When the checkbox label is too long for space available, it wraps to form another line. The checkbox button remains vertically aligned to the top line of the label.

Checkbox label text overflowing to the next line, as described in the caption below. — When text length is longer than its space, it overflows. Note how it makes the checkbox label look disorganized.

Interactions

Mouse

Users can select or deselect an option by clicking on the checkbox or its label.
When the cursor moves over a selectable checkbox or its label, the cursor icon changes from an arrow to a pointer hand.
When hovering over a disabled checkbox, the cursor indicates the item is not selectable by transforming into the error icon.

A cursor changing its icon once it hovers over checkboxes in different states, as described in the caption below. — The cursor’s icon will change depending on the state of the checkbox being hovered.

Keyboard focus

Users can select a checkbox with the Tab and Space keys. The Tab key cycles through each available checkbox, and the Space key checks or unchecks the highlighted option.

Layout

Position the checkbox options vertically, with one choice per line. When using a horizontal layout that has more than one checkbox in every line, place the buttons and labels so users can tell which checkbox matches each label. Laying them out horizontally can make it hard for users to connect each checkbox with its proper label.

A vertically aligned checkbox group above a horizontally aligned checkbox group, which should be used sparingly. — Checkbox groups should be aligned vertically when possible.

Get in touch

Do you have an idea, or want to help us improve this page? Reach out to us via email.

DTMB-DG-Support@michigan.gov

Need help? Visit our Support page to learn how to get assistance, troubleshoot issues, and connect with the team.