Checkbox

Storybook Source

Form control for selecting zero, one, or many options.

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

Label size

Use the label-size prop to override the default label size.

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.

Vue API 

import { DtCheckbox } from '@dialpad/dialtone-vue';

Slots

Name
Type
default

slot for Checkbox Label

description

slot for Checkbox Description

Props

Name
Default
Type
description
''
string

Describes the input

descriptionChildProps
{}
object

A set of props that are passed into the description container

descriptionClass
''
string|array|object

Used to customize the description container

disabled
false
boolean

Disables the input

indeterminate
false
boolean

Indeterminate State, toggling indeterminate checkbox will uncheck

inputClass
''
string|array|object

Used to customize the input element

label
''
string

A provided label for the input

labelChildProps
{}
object

A set of props that are passed into the label container

labelClass
''
string|array|object

Used to customize the label container

labelSize
null
"100" | "200" | "300" | "400"

Overrides the label text size.

labelStrength
null
"bold" | "semibold" | "medium" | "normal"

Overrides the label font weight.

messages
[]
array

Validation messages

messagesChildProps
{}
object

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

messagesClass
''
string|array|object

Used to customize the validation messages component

name
''
string

The name of the input

showLabel
true
"true" | "false"

Determines visibility of checkbox label.

showMessages
true
"true" | "false"

Used to hide / show the validation messages

v-model
false
boolean

Used to set the checked state of the checkable input

validationState
''
string

The validation state of the input

value
null
string|number|boolean

The value of the input

Events

Name
Type
focusin
FocusEvent

Native input focusin event

focusout
FocusEvent

Native input focusout event

update:modelValue
Boolean

Event fired to sync the modelValue prop with the parent component

Classes

Class
Applies to
Description

Checkbox documentation last updated Friday, September 4, 2026

fix/popover-modal-zindex-scope