Checkbox

Since 2.6.0 Form-ready since 2.6.0

Show deprecated version

Guidelines

Guidelines

A checkbox is a small interactive box that allows the user to toggle between an affirmative or negative choice. Checkboxes are commonly used when there are multiple options that can be selected or to easily enable or disable a setting. They are often utilized in forms where users can choose multiple options, such as selecting items or categories that apply to a specific product or service.

1. Checkbox
2. Checkbox label
3. Group label
4. Group required indicator
5. Group helper or feedback text

Options

• Checkbox label: See form field.
• Indeterminate checkbox: Indicates that only some items in a checkbox group are selected. We offer the indeterminate state, but the implementation when this state is active is the responsibility of each individual.
• Checkbox group: Group checkboxes to indicate that they are related. We typically use checkbox groups when multiple options need to be presented for selection, allowing users to choose any combination of the available choices. They are particularly useful in user interface design for forms, settings and preferences where multiple selections are possible.
• Group label: Add a label to the group of checkboxes to provide context to your users. We typically use short and descriptive labels to summarize the options in the group.
• Group helper text: See form field.
• Group feedback text: See form field.

Behavior in context

• Validation: See validation.
• Interaction: Clicking on the checkbox toggles the state between checked and unchecked.
• Grouping: Checkbox groups have only one label and helper text for the entire group. Grouped checkboxes are validated collectively, not individually.

States

Dos and Don’ts

• Do use checkboxes when you have multiple options that can be selected
• Do group related checkboxes together to indicate their relationship
• Do use checkboxes in forms to allow users to select multiple options
• Don’t use a checkbox for binary choices (yes/no, true/false) - use a toggle switch instead
• Don’t use checkboxes for mutually exclusive options - use radio buttons instead
• Don’t use checkboxes for actions that have immediate consequences - use buttons or links instead

Development

Development

Examples

Basic

PreviewAngularReactVueJavaScript

Disabled

PreviewAngularReactVueJavaScript

Group

PreviewAngularReactVueJavaScript

Indeterminate group

PreviewAngularReactVueJavaScript

Validation

PreviewAngularReactVueJavaScript

API

Properties

Name

Description and specifications

checked

Checked state of the checkbox component

Attribute:

checked

Type:

boolean

Default:

false

disabled

Disabled state of the checkbox component

Attribute:

disabled

Type:

boolean

Default:

false

indeterminate

Indeterminate state of the checkbox component

Attribute:

indeterminate

Type:

boolean

Default:

false

label

Label for the checkbox component

Attribute:

label

Type:

string ｜ undefined

name

Name of the checkbox component

Attribute:

name

Type:

string ｜ undefined

required

Required state of the checkbox component. If true, checkbox needs to be checked to be valid

Attribute:

required

Type:

boolean

Default:

false

value

Value of the checkbox component

Attribute:

value

Type:

string

Default:

'on'

Events

Name

Description and specifications

checkedChange

Event emitted when the checked state of the checkbox changes

Detail:

boolean

valueChange

Event emitted when the value of the checkbox changes

Detail:

string