Components/Form
Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/checkbox
Checkboxes allows to select single or multiple items from a list of predefined options.
<RadioGroup/> instead.<ToggleSwitch/> instead.<MultiSelectCheckbox/>, <MultiSelect/> or <SelectorList/> instead.Adjust the component size using the size prop. It supports 2 sizes:
medium (default) - use in all common casessmall - use in more dense layoutsA checkbox can exist in multiple states:
default state, the checkbox is empty and the user is able to select it.checked - the selected item is marked.indeterminate - represent a mixed value for bulk selection checkbox (both selected and not selected values included).disabled - highlight that a selection exists but it's not available at that time.Add text that explains the status or what action the user should take with the statusMessage prop.
Show the status message inline, directly below the checkboxes by wrapping them in a <FormField/> and adding statusMessage.
View more inline status message examples in <FormField/>.
Control checkbox alignment with a label using the vAlign prop. It supports 2 values:
center (default) - use it in all common casestop - use it to align the checkbox to the top to handle text overflowEmphasize the clickable space with a selection area. Control the style with:
selectionArea - to specify whether to display an area on hover, always or not display it at allselectionAreaSkin - to specify which design to use: filled or outlineselectionAreaPadding - to define white space around the checkbox in pixelsUse maxLines prop to limit the amount of lines and show ellipsis.
Use a tooltip to give added explanation for the checkbox. Use the tooltipContent prop, and control the design with tooltipProps (it accepts all standard <Tooltip/> properties).
Use checkboxes in a form to display all available options.
Use any component for checkbox labels, make sure that they are either textual components or self-explanatory within the given context.
Use checkboxes to manage which elements of an app are visible on your site.
| Name | Type | Default | Description |
|---|---|---|---|
checked | boolean | — | Specifies whether a checkbox is selected. |
children | ReactNode | — | Defines a checkbox label. |
dataHook | string | — | Applies a data-hook HTML attribute that can be used in tests. |
disabled | boolean | — | Specifies whether a checkbox is disabled. |
ellipsis | boolean | — | Truncates text that is longer than its parent container and displays ellipsis at the end of the last line. |
errorMessage | string | — | The error message when there's an error. |
hasError | boolean | — | Specifies whether a checkbox has an error. |
id | string | — | Assigns a unique identifier for the checkbox. |
indeterminate | boolean | — | Specifies whether a checkbox is in an indeterminate state. |
maxLines | number | — | Truncates label text at a specific number of lines when using ellipsis. |
onBlur | (event: FocusEvent, triggers: Triggers) => void | — | |
onChange | ChangeEventHandler | — | Defines a callback function which is called every time the checkbox state is changed. |
onFocus | (event: FocusEvent, triggers: Triggers) => void | — | |
ref | RefObject | — | |
required | boolean | — | Specifies whether a checkbox is required. |
selectionArea | "none" | "hover" | "always" | — | Controls the selection area highlight visibility. |
selectionAreaPadding | string | number | string & {} | — | Sets the amount of white space around the checkbox label in pixels. |
selectionAreaSkin | "filled" | "outlined" | — | Sets the design of the selection area. |
size | "small" | "medium" | — | Controls the size of the checkbox label. |
tooltipContent | ReactNode | — | Defines a message to be displayed in a tooltip. Tooltip is displayed on a checkbox hover. |
tooltipProps | TooltipCommonProps | — | Allows you to pass all common tooltip props. |
vAlign | "center" | "top" | — | Controls checkbox alignment to the label on the Y axis. |
Import the driver matching your test environment:
| Method | Description |
|---|---|
click | Click on the component root element. |
focus | focuses the component. |
isFocused | Checks whether the checkbox is focused |
blur | blurs off the element. |
isChecked | Checks whether the checkbox is checked. |
isDisabled | Checks whether the checkbox is disabled. |
isRequired | Checks whether the checkbox is required. |
isIndeterminate | Checks whether the checkbox's value is indeterminate. |
isTooltipEnabled | Checks whether the checkbox's tooltip is enabled. |
hasError | Checks whether the checkbox hasError prop is true. |
getTooltipContent | Gets the tooltip message. |
getLabel | Gets checkbox's label. |
getLabelSize | Gets the label's size. |
exists | Checks whether the component found with the given data hook. |
element | Gets the component root element. |
base | Returns UniDriver for the base element. |
click() method toggles the checkbox in browser tests without activating links or other interactive elements in its label. (#17317)Last updated: 22 October 2026