Checkbox

Storybook Figma

A checkbox is an input control that allows users to select zero, one, or more options from a number of choices.

Preview

Usage

Checkboxes are an easily understandable way to indicate that users can select one or more answers to a question or items from a list. They visibly show users what’s been selected and makes it easy for them to “uncheck” an option, which can be difficult with other selection methods on a form (such as radio buttons or select menus).

Do

  • Selecting any number of choices from a set list.
  • Binary selections that convey opposite states, such as check=“on” and unchecked=“off”, paired with a label that conveys the choice.
  • When users need to see all the available options at a glance.

Don’t

  • If a user can only select one option from a list; consider using Radio or Select.
  • If there are too many options to reasonably display in its context.

Best Practices

  • Users should be able to tap on or click on either the text label or the checkbox element itself to toggle an option, aiding accessibility.
  • Options that are listed vertically are easier to read than those listed horizontally. Horizontal listings can make it difficult to tell which label pertains to which checkbox.
  • Negative language in labels can be counterintuitive. For example, use "I want to receive a promotional email" instead of "I don’t want to receive promotional email".
  • Make sure that the label makes both states — checked and unchecked — clear to the user. If that’s not possible, consider using a Radio button with two individual options instead. Then both states can have their own clearly marked label.
  • Make sure selections are adequately spaced for touch screens.
  • Multiple checkbox options should be organized in a meaningful way, like alphabetical or most-frequent to least-frequent. This helps users easily find the option they’re looking for.
  • indeterminate checkboxes convey a "mixed" state that neither qualifies as checked or unchecked. An example use case is when a checkbox acts as a "parent" of a collection of child checkboxes:
    • checked: all children are checked.
    • unchecked: all children are not checked.
    • indeterminate: children are a mix of checked and unchecked.

Variants and Examples

Base Styles

Indeterminate

Stacked Group

With Description Text

With Validation States

Vue API

Slots

Name
Description
default

slot for Checkbox Label
description

slot for Checkbox Description

Props

Name
Description
Default
description

Describes the input

 Type: string
''
descriptionChildProps

A set of props that are passed into the description container

 Type: object
{}
descriptionClass

Used to customize the description container

 Type: string|array|object
''
disabled

Disables the input

 Type: boolean
false
indeterminate

Indeterminate State, toggling indeterminate checkbox will uncheck

 Type: boolean
false
inputClass

Used to customize the input element

 Type: string|array|object
''
label

A provided label for the input

 Type: string
''
labelChildProps

A set of props that are passed into the label container

 Type: object
{}
labelClass

Used to customize the label container

 Type: string|array|object
''
messages

Validation messages

 Type: array
[]
messagesChildProps

A set of props that are passed into the validation messages component

 Type: object
{}
messagesClass

Used to customize the validation messages component

 Type: string|array|object
''
name

The name of the input

 Type: string
''
rootClass

Additional class name for the root element. Can accept all of: String, Object, and Array, i.e. has the same api as Vue's built-in handling of the class attribute.

 Type: string|object|array
''
showMessages

Used to hide / show the validation messages

 Type: boolean
Values: truefalse
 true
v-model

Used to set the checked state of the checkable input

 Type: boolean
false
validationState

The validation state of the input

 Type: string
''
value

The value of the input

 Type: string|number|boolean
null

Events

Name
Description
focusin

Native input focusin event

 Type: FocusEvent
focusout

Native input focusout event

 Type: FocusEvent
input

Native input event

 Type: Boolean
update:modelValue

Event fired to sync the modelValue prop with the parent component

 Type: Boolean

Classes

Class
Applies to
Description

Accessibility

The best accessibility is semantic HTML. Most screen readers understand how to parse inputs if they’re correctly formatted. When it comes to checkboxes, there are a few things to keep in mind:

  • All inputs should have an id attribute.
  • Associate checkbox labels with their inputs using the for attribute. This correlates with the checkbox's id.
  • If you have a group of related checkboxes, use a fieldset to group them and a legend to title the group. For further information, please visit Gov.UK’s article, "Using the fieldset and legend elements".
  • Input with description text should have aria-describedby with the id of the description text.
  • If the input is a required field, use the aria-required property and use the validation message for input errors.
  • Input with validation errors should have aria-describedby with the id of the validation message.
Checkbox documentation last updated Thursday, June 11, 2026