> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Checkbox Component

## Article: Checkbox Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/form/checkbox-component.md

## Article Content:

# Checkbox

_Components/Form_

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

## Overview

```jsx
() => {
  const checkboxes = [
    {
      id: 'theater',
      label: 'Theater',
      initialValue: true,
    },
    {
      id: 'architecture',
      label: 'Architecture',
      initialValue: true,
    },
    {
      id: 'music',
      label: 'Music',
      initialValue: true,
    },
    {
      id: 'sports',
      label: 'Sports',
      initialValue: false,
    },
  ];

  return (
    <Box align="center">
      <StorybookComponents.Stack gap="12px" flexDirection="column">
        {checkboxes.map((item) => {
          const [checked, setChecked] = React.useState(item.initialValue);

          return (
            <Checkbox
              id={item.id}
              checked={checked}
              onChange={() => setChecked(!checked)}
            >
              {item.label}
            </Checkbox>
          );
        })}
      </StorybookComponents.Stack>
    </Box>
  );
};
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Checkbox size="medium">Medium</Checkbox>
  <Checkbox size="small">Small</Checkbox>
</StorybookComponents.Stack>;
```

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

```jsx
<StorybookComponents.Stack flexDirection="column">
  <Checkbox>Default</Checkbox>
  <Checkbox checked>Checked</Checkbox>
  <Checkbox indeterminate>Indeterminate</Checkbox>
  <Checkbox disabled>Disabled</Checkbox>
</StorybookComponents.Stack>;
```

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

```jsx
<FormField status="error" statusMessage="This is an error message.">
  <StorybookComponents.Stack flexDirection="column" gap="12px">
    <Checkbox>Option 1</Checkbox>
    <Checkbox>Option 2</Checkbox>
  </StorybookComponents.Stack>
</FormField>;
```

#### 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

```jsx
<StorybookComponents.Stack width="300px" flexDirection="column">
  <Checkbox vAlign="center">
    Checkbox label that wraps to multiple lines (center)
  </Checkbox>
  <Checkbox vAlign="top">
    Checkbox label that wraps to multiple lines (top)
  </Checkbox>
</StorybookComponents.Stack>;
```

#### 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

```jsx
<StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" width="50%">
    <Checkbox
      selectionArea="always"
      selectionAreaSkin="outlined"
      selectionAreaPadding="12px 18px"
      checked
    >
      Option 1
    </Checkbox>
    <Checkbox
      selectionArea="always"
      selectionAreaSkin="outlined"
      selectionAreaPadding="12px 18px"
    >
      Option 2
    </Checkbox>
    <Checkbox
      selectionArea="always"
      selectionAreaSkin="outlined"
      selectionAreaPadding="12px 18px"
    >
      Option 3
    </Checkbox>
  </StorybookComponents.Stack>
  <StorybookComponents.Stack flexDirection="column" width="50%">
    <Checkbox
      selectionArea="hover"
      selectionAreaSkin="filled"
      selectionAreaPadding="12px 18px"
      checked
    >
      Option 1
    </Checkbox>
    <Checkbox
      selectionArea="hover"
      selectionAreaSkin="filled"
      selectionAreaPadding="12px 18px"
    >
      Option 2
    </Checkbox>
    <Checkbox
      selectionArea="hover"
      selectionAreaSkin="filled"
      selectionAreaPadding="12px 18px"
    >
      Option 3
    </Checkbox>
  </StorybookComponents.Stack>
</StorybookComponents.Stack>;
```

#### Max lines

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

```jsx
<StorybookComponents.Stack width="300px" flexDirection="column">
  <Checkbox>Checkbox label that wraps to multiple lines</Checkbox>
  <Checkbox ellipsis={true} maxLines="1">
    Checkbox label that has max lines applied
  </Checkbox>
</StorybookComponents.Stack>;
```

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

```jsx
<Checkbox
  tooltipContent="Message explaining the select option"
  tooltipProps={{
    placement: 'top-start',
    textAlign: 'start',
  }}
>
  Hover the mouse on a checkbox to see a tooltip
</Checkbox>;
```

### Common use case examples

#### Forms

Use checkboxes in a form to display all available options.

```jsx
() => {
  const checkboxes = [
    {
      id: 'newArrivals',
      label: 'New Arrivals',
      isChecked: true,
    },
    {
      id: 'womensClothing',
      label: "Women's clothing",
      isChecked: true,
    },
    {
      id: 'mensClothing',
      label: "Men's clothing",
      isChecked: false,
    },
    {
      id: 'kids',
      label: 'Kids',
      isChecked: false,
    },
    {
      id: 'home',
      label: 'Home',
      isChecked: false,
    },
  ];

  const [checkboxesList, setCheckboxesList] = React.useState(checkboxes);

  const isAllSelected = !checkboxesList
    .map((item) => item.isChecked)
    .includes(false);

  const isAllDeselected = !checkboxesList
    .map((item) => item.isChecked)
    .includes(true);

  const toggleCheckedAll = (checked) => {
    setCheckboxesList(
      checkboxesList.map((item) => ({ ...item, isChecked: checked })),
    );
  };

  const renderCheckboxes = () =>
    checkboxesList.map((item) => (
      <Checkbox
        id={item.id}
        checked={item.isChecked}
        onChange={() =>
          setCheckboxesList(
            checkboxesList.map((other) =>
              other.id === item.id
                ? { ...other, isChecked: !other.isChecked }
                : other,
            ),
          )
        }
      >
        {item.label}
      </Checkbox>
    ));

  return (
    <Layout>
      <Cell span={6}>
        <Card>
          <Card.Header
            title="Collections"
            subtitle="Assign products to a collection"
          />
          <Card.Divider />
          <Card.Content>
            <Box direction="vertical" gap="12px">
              <Checkbox
                checked={isAllSelected || (!isAllSelected && !isAllDeselected)}
                onChange={() => {
                  isAllSelected
                    ? toggleCheckedAll(false)
                    : toggleCheckedAll(true);
                }}
                disabled={!isAllSelected && !isAllDeselected}
              >
                All products
              </Checkbox>
              {renderCheckboxes()}
              <TextButton prefixIcon={<Icons.Add />}>
                Create Collection
              </TextButton>
            </Box>
          </Card.Content>
        </Card>
      </Cell>
    </Layout>
  );
};
```

#### With a label

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

```jsx
() => {
  const checkboxes = [
    {
      id: 'members',
      label: 'Members',
      description: 'All registered users',
      isChecked: true,
    },
    {
      id: 'roles',
      label: 'Roles',
      description: 'Users who are assigned to a special role',
      isChecked: false,
    },
    {
      id: 'badges',
      label: 'Badges',
      description: 'Users who have selected badges',
      isChecked: false,
    },
  ];

  const getCheckboxLabel = (item) => (
    <Box direction="vertical">
      <Text weight="bold">{item.label}</Text>
      <Text size="small" secondary>
        {item.description}
      </Text>
    </Box>
  );

  const renderCheckboxes = () => {
    return checkboxes.map((item) => {
      const [checked, setChecked] = React.useState(item.isChecked);

      return (
        <Checkbox
          checked={checked}
          onChange={() => setChecked(!checked)}
          selectionArea="hover"
          id={item.id}
        >
          {getCheckboxLabel(item)}
        </Checkbox>
      );
    });
  };

  return (
    <Card>
      <Card.Header title="Permissions" />
      <Card.Divider />
      <Card.Content>
        <Box direction="vertical">
          <FormField label="Who can access this category?">
            <Box direction="vertical" gap="12px">
              {renderCheckboxes()}
            </Box>
          </FormField>
        </Box>
      </Card.Content>
    </Card>
  );
};
```

#### Manage panel

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

```jsx
<SidePanel
  onCloseButtonClick={() => {}}
  skin="floating"
  width="288px"
  height="576px"
>
  <SidePanel.Header title="Widget Elements" />
  <SidePanel.Content noPadding>
    <SidePanel.Field divider={false}>
      <Text size="small" secondary>
        Choose which elements to display on Post Header
      </Text>
    </SidePanel.Field>
    <SidePanel.Field divider={false}>
      <FieldSet legend="Main elements" direction="vertical">
        <Checkbox checked size="small">
          Categories
        </Checkbox>
        <Checkbox checked size="small">
          Title
        </Checkbox>
        <Checkbox checked size="small">
          Ratings
        </Checkbox>
        <Checkbox checked size="small">
          Tags
        </Checkbox>
        <Checkbox checked size="small">
          Writers
        </Checkbox>
        <Checkbox checked size="small">
          Counters
        </Checkbox>
      </FieldSet>
    </SidePanel.Field>
    <SidePanel.Field divider={false}>
      <Divider />
    </SidePanel.Field>
    <SidePanel.Field divider={false}>
      <FieldSet legend="Metadata" direction="vertical">
        <Checkbox checked size="small">
          Categories
        </Checkbox>
        <Checkbox checked size="small">
          Writer
        </Checkbox>
        <Checkbox checked size="small">
          Publish date
        </Checkbox>
        <Checkbox checked size="small">
          Reading time
        </Checkbox>
        <Checkbox checked size="small">
          Last updated
        </Checkbox>
      </FieldSet>
    </SidePanel.Field>
    <SidePanel.Field divider={false}>
      <Divider />
    </SidePanel.Field>
    <SidePanel.Field divider={false}>
      <FieldSet legend="Counters" direction="vertical">
        <Checkbox checked size="small">
          Likes
        </Checkbox>
        <Checkbox checked size="small">
          Views
        </Checkbox>
        <Checkbox checked size="small">
          Comments
        </Checkbox>
      </FieldSet>
    </SidePanel.Field>
  </SidePanel.Content>
</SidePanel>;
```

## Code

```jsx
import { Checkbox } from '@wix/design-system';
```

### Props

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

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { CheckboxUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { CheckboxTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { CheckboxTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { CheckboxTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

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

## 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](invalid-url))
- **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](invalid-url))
- **1.194.0** (2025-05-30) — fix: make checkbox scrollable to on focus ([#14903](invalid-url))
- **1.191.1** (2025-05-27) — fix: fix screen reader checkbox clickability ([#14873](invalid-url))
- **1.183.0** (2025-04-24) — maintenance release, no component-specific changes
- **1.181.0** (2025-04-18) — feat: add required prop ([#14746](invalid-url))
- **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](invalid-url))
- **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