Checkbox

Components/Form

Interactive docs page: https://wix-pages.com/design-system-documentation/#/component/checkbox

Overview

Copy

Checkboxes allows to select single or multiple items from a list of predefined options.

Do

  • Use it in forms to select one or multiple items from a list of options.
  • Use it when all options need to be displayed right away.
  • Use it when an explicit action is required to apply a setting, e.g., Agree to terms and conditions.

Don't

  • Don't use it to select a single item from a list. Use <RadioGroup/> instead.
  • Don't use it to activate a setting or a feature. Use <ToggleSwitch/> instead.
  • Don't use it to select more than 5-10 options, use <MultiSelectCheckbox/>, <MultiSelect/> or <SelectorList/> instead.

Feature examples

Size

Adjust the component size using the size prop. It supports 2 sizes:

  • medium (default) - use in all common cases
  • small - use in more dense layouts
Copy

State

A checkbox can exist in multiple states:

  • In the 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.
Copy

Status message

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/>.

Copy

Vertical alignment

Control checkbox alignment with a label using the vAlign prop. It supports 2 values:

  • center (default) - use it in all common cases
  • top - use it to align the checkbox to the top to handle text overflow
Copy

Selection area

Emphasize 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 all
  • selectionAreaSkin - to specify which design to use: filled or outline
  • selectionAreaPadding - to define white space around the checkbox in pixels
Copy

Max lines

Use maxLines prop to limit the amount of lines and show ellipsis.

Copy

Tooltip

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).

Copy

Common use case examples

Forms

Use checkboxes in a form to display all available options.

Copy

With a label

Use any component for checkbox labels, make sure that they are either textual components or self-explanatory within the given context.

Copy

Manage panel

Use checkboxes to manage which elements of an app are visible on your site.

Copy

Code

Copy

Props

NameTypeDefaultDescription
checkedboolean—Specifies whether a checkbox is selected.
childrenReactNode—Defines a checkbox label.
dataHookstring—Applies a data-hook HTML attribute that can be used in tests.
disabledboolean—Specifies whether a checkbox is disabled.
ellipsisboolean—Truncates text that is longer than its parent container and displays ellipsis at the end of the last line.
errorMessagestring—The error message when there's an error.
hasErrorboolean—Specifies whether a checkbox has an error.
idstring—Assigns a unique identifier for the checkbox.
indeterminateboolean—Specifies whether a checkbox is in an indeterminate state.
maxLinesnumber—Truncates label text at a specific number of lines when using ellipsis.
onBlur(event: FocusEvent, triggers: Triggers) => void—
onChangeChangeEventHandler—Defines a callback function which is called every time the checkbox state is changed.
onFocus(event: FocusEvent, triggers: Triggers) => void—
refRefObject—
requiredboolean—Specifies whether a checkbox is required.
selectionArea"none" | "hover" | "always"—Controls the selection area highlight visibility.
selectionAreaPaddingstring | 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.
tooltipContentReactNode—Defines a message to be displayed in a tooltip. Tooltip is displayed on a checkbox hover.
tooltipPropsTooltipCommonProps—Allows you to pass all common tooltip props.
vAlign"center" | "top"—Controls checkbox alignment to the label on the Y axis.

Testkit

Import the driver matching your test environment:

Copy

Driver methods

MethodDescription
clickClick on the component root element.
focusfocuses the component.
isFocusedChecks whether the checkbox is focused
blurblurs off the element.
isCheckedChecks whether the checkbox is checked.
isDisabledChecks whether the checkbox is disabled.
isRequiredChecks whether the checkbox is required.
isIndeterminateChecks whether the checkbox's value is indeterminate.
isTooltipEnabledChecks whether the checkbox's tooltip is enabled.
hasErrorChecks whether the checkbox hasError prop is true.
getTooltipContentGets the tooltip message.
getLabelGets checkbox's label.
getLabelSizeGets the label's size.
existsChecks whether the component found with the given data hook.
elementGets the component root element.
baseReturns UniDriver for the base element.

Changelog

  • 1.340.0 (2026-10-21) — maintenance release, no component-specific changes
  • 1.339.0 (2026-10-19) — maintenance release, no component-specific changes
  • 1.338.0 (2026-10-15) — maintenance release, no component-specific changes
  • 1.332.0 (2026-10-05) — fix: the test driver's click() method toggles the checkbox in browser tests without activating links or other interactive elements in its label. (#17317)
  • 1.330.0 (2026-09-28) — maintenance release, no component-specific changes
  • 1.329.0 (2026-09-24) — maintenance release, no component-specific changes
  • 1.328.0 (2026-09-22) — maintenance release, no component-specific changes
  • 1.325.0 (2026-09-17) — maintenance release, no component-specific changes
  • 1.323.0 (2026-09-10) — maintenance release, no component-specific changes
  • 1.310.0 (2026-08-10) — maintenance release, no component-specific changes
  • 1.292.0 (2026-06-22) — maintenance release, no component-specific changes
  • 1.291.0 (2026-06-19) — maintenance release, no component-specific changes
  • 1.278.0 (2026-05-08) — maintenance release, no component-specific changes
  • 1.277.0 (2026-05-07) — maintenance release, no component-specific changes
  • 1.273.0 (2026-04-30) — maintenance release, no component-specific changes
  • 1.272.0 (2026-04-27) — maintenance release, no component-specific changes
  • 1.266.0 (2026-04-07) — maintenance release, no component-specific changes
  • 1.260.0 (2026-03-17) — maintenance release, no component-specific changes
  • 1.254.0 (2026-02-03) — maintenance release, no component-specific changes
  • 1.250.0 (2026-01-27) — maintenance release, no component-specific changes
  • 1.247.2 (2026-01-21) — maintenance release, no component-specific changes
  • 1.213.0 (2025-08-19) — maintenance release, no component-specific changes
  • 1.212.0 (2025-08-11) — maintenance release, no component-specific changes
  • 1.209.0 (2025-07-30) — breaking: editor3 tokenization (#15119)
  • 1.194.0 (2025-05-30) — fix: make checkbox scrollable to on focus (#14903)
  • 1.191.1 (2025-05-27) — fix: fix screen reader checkbox clickability (#14873)
  • 1.183.0 (2025-04-24) — maintenance release, no component-specific changes
  • 1.181.0 (2025-04-18) — feat: add required prop (#14746)
  • 1.144.0 (2024-12-03) — maintenance release, no component-specific changes
  • 1.143.0 (2024-11-25) — maintenance release, no component-specific changes
  • 1.138.1 (2024-10-30) — maintenance release, no component-specific changes
  • 1.128.0 (2024-09-19) — maintenance release, no component-specific changes
  • 1.115.0 (2024-07-17) — maintenance release, no component-specific changes
  • 1.112.0 (2024-07-03) — fix: clicking label would trigger click twice (#13874)
  • 1.104.1 (2024-05-14) — maintenance release, no component-specific changes
  • 1.103.3 (2024-04-30) — maintenance release, no component-specific changes
  • 1.102.0 (2024-04-16) — maintenance release, no component-specific changes
  • 1.92.1 (2024-02-05) — maintenance release, no component-specific changes

Last updated: 22 October 2026

Did this help?