Skip to main content

CheckBox

<ui5-checkbox>

Allows the user to set a binary value, such as true/false or yes/no for an item.

The ui5-checkbox component consists of a box and a label that describes its purpose. If it's checked, an indicator is displayed inside the box. To check/uncheck the ui5-checkbox, the user has to click or tap the square box or its label.

The ui5-checkbox component only has 2 states - checked and unchecked. Clicking or tapping toggles the ui5-checkbox between checked and unchecked state.

Usage​

You can define the checkbox text with via the text property. If the text exceeds the available width, it is truncated by default. In case you prefer text to truncate, set the wrappingType property to "None". The touchable area for toggling the ui5-checkbox ends where the text ends.

You can disable the ui5-checkbox by setting the disabled property to true, or use the ui5-checkbox in read-only mode by setting the readonly property to true.

Keyboard Handling​

The user can use the following keyboard shortcuts to toggle the checked state of the ui5-checkbox.

  • [Space],[Enter] - Toggles between different states: checked, not checked.

ES6 Module Import​

import "@ui5/webcomponents/dist/CheckBox.js";

Basic Sample​

Properties​

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the component
Typestring | undefined
Defaultundefined
Since1.1.0

accessibleName​

DescriptionDefines the accessible ARIA name of the component.
Typestring | undefined
Defaultundefined
Since1.1.0

disabled​

DescriptionDefines whether the component is disabled.
Note: A disabled component is completely noninteractive.
Typeboolean
Defaultfalse

readonly​

DescriptionDefines whether the component is read-only.
Note: A read-only component is not editable, but still provides visual feedback upon user interaction.
Typeboolean
Defaultfalse

displayOnly​

DescriptionDetermines whether the ui5-checkbox is in display only state.
When set to true, the ui5-checkbox is not interactive, not editable, not focusable and not in the tab chain. This setting is used for forms in review mode.
Note: When the property disabled is set to true this property has no effect.
Typeboolean
Defaultfalse
Since1.22.0

required​

DescriptionDefines whether the component is required.
Typeboolean
Defaultfalse
Since1.3.0

indeterminate​

DescriptionDefines whether the component is displayed as partially checked.
Note: The indeterminate state can be set only programmatically and can’t be achieved by user interaction and the resulting visual state depends on the values of the indeterminate and checked properties:
- If the component is checked and indeterminate, it will be displayed as partially checked
- If the component is checked and it is not indeterminate, it will be displayed as checked
- If the component is not checked, it will be displayed as not checked regardless value of the indeterminate attribute
Typeboolean
Defaultfalse
Since1.0.0-rc.15

checked​

DescriptionDefines if the component is checked.
Note: The property can be changed with user interaction, either by cliking/tapping on the component, or by pressing the Enter or Space key.
Typeboolean
Defaultfalse

text​

DescriptionDefines the text of the component.
Typestring | undefined
Defaultundefined

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Positive" | "Critical" | "Negative" | "Information"
Default"None"

wrappingType​

DescriptionDefines whether the component text wraps when there is not enough space.
Note: for option "Normal" the text will wrap and the words will not be broken based on hyphenation. Note: for option "None" the text will be truncated with an ellipsis.
Type"None" | "Normal"
Default"Normal"

name​

DescriptionDetermines the name by which the component will be identified upon submission in an HTML form.
Note: This property is only applicable within the context of an HTML Form element.
Typestring | undefined
Defaultundefined

Slots​

No slots available for this component.

Events​

change​

DescriptionFired when the component checked state changes.
TypeCustomEvent
BubblesYes
CancelableYes - via preventDefault()

Methods​

No methods available for this component.

CSS Parts​

NameDescription
rootUsed to style the outermost wrapper of the ui5-checkbox
labelUsed to style the label of the ui5-checkbox
iconUsed to style the icon of the ui5-checkbox

More Samples​

Indeterminate​

The CheckBox can also display an indeterminate state. It's usefull to indicate that not all tasks/items are done/checked.

States​

CheckBox supports several semantic value states, readonly, disabled, etc.

Text Truncation and Wrapping​

The CheckBox text wraps by default. To make it truncate - set wrapping-type="None".