> For the complete documentation index, see [llms.txt](https://docs.webstudio.is/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.webstudio.is/university/core-components/checkbox.md).

# Checkbox

Add checkbox inputs to forms in Webstudio.

> See [MDN: \<input type="checkbox">](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox)

The **Checkbox** component creates an HTML checkbox input for boolean selections.

## Overview

Checkboxes allow users to select one or more options from a set, or toggle a single option on/off.

## Properties

| Property   | Type    | Description                     |
| ---------- | ------- | ------------------------------- |
| `name`     | string  | Form field name                 |
| `value`    | string  | Value submitted when checked    |
| `checked`  | boolean | Whether the checkbox is checked |
| `required` | boolean | Whether selection is required   |
| `disabled` | boolean | Whether input is disabled       |
| `id`       | string  | Unique identifier               |
| `class`    | string  | CSS class names                 |

## Basic Usage

### Single Checkbox

For a single yes/no option:

```
Label (display: flex, align-items: center, gap: 8px)
├── Checkbox (name: newsletter, value: yes)
└── "Subscribe to newsletter"
```

### Checkbox Group

For multiple selections:

```
Box
├── Label
│   ├── Checkbox (name: interests, value: design)
│   └── "Design"
├── Label
│   ├── Checkbox (name: interests, value: development)
│   └── "Development"
└── Label
    ├── Checkbox (name: interests, value: marketing)
    └── "Marketing"
```

When submitted, all checked values are sent with the same `name`.

## Styling Checkboxes

### Native Styling

Browser checkboxes can be styled with:

* `accent-color`: Change the checked color
* `width`/`height`: Adjust size
* `cursor: pointer`: Show clickable cursor

### Custom Checkbox

For fully custom checkboxes, consider using the [Radix Checkbox](https://docs.webstudio.is/university/radix/checkbox.md) component, which provides complete styling control while maintaining accessibility.

## Form Submission

### Single Checkbox

If checked, sends: `name=value` If unchecked, nothing is sent

### Multiple Checkboxes (same name)

Sends all checked values: `interests=design&interests=development`

## Validation

### Required Checkbox

For required checkboxes (like terms acceptance):

```
Label
├── Checkbox (name: terms, required: true)
└── "I agree to the terms and conditions"
```

The form won't submit until the checkbox is checked.

## Accessibility

1. **Always use labels**: Associate every checkbox with a label
2. **Group related checkboxes**: Use fieldset and legend for groups
3. **Provide clear labels**: Make options self-explanatory
4. **Keyboard support**: Ensure checkboxes work with Space key

### Grouping with Fieldset

```
Box (role: group)
├── Text (role: legend) → "Notification Preferences"
├── Label
│   ├── Checkbox (name: notify, value: email)
│   └── "Email notifications"
└── Label
    ├── Checkbox (name: notify, value: sms)
    └── "SMS notifications"
```

## States

Style different checkbox states:

| State         | Description                         |
| ------------- | ----------------------------------- |
| Unchecked     | Default empty state                 |
| Checked       | Selected state                      |
| Disabled      | Cannot be interacted with           |
| Focus         | Keyboard focus visible              |
| Indeterminate | Partial selection (JavaScript only) |

## Best Practices

1. **Use for multiple selections**: Use checkboxes when users can select multiple options
2. **Label clickable**: Make entire label area clickable
3. **Vertical alignment**: Stack checkboxes vertically for easier scanning
4. **Reasonable defaults**: Pre-check options when appropriate
5. **Clear labeling**: Use positive phrasing (what happens when checked)

## When to Use

| Use Checkbox        | Use Radio                  | Use Toggle       |
| ------------------- | -------------------------- | ---------------- |
| Multiple selections | Single selection from many | On/off setting   |
| Optional agreements | Required choice            | Immediate effect |
| Filter options      | Exclusive options          | Settings         |

## Related Components

* [RadioButton](https://docs.webstudio.is/university/core-components/radio-button.md) - Single selection from multiple options
* [Switch](https://docs.webstudio.is/university/radix/switch.md) - Toggle on/off (Radix)
* [Radix Checkbox](https://docs.webstudio.is/university/radix/checkbox.md) - Fully customizable checkbox
* [Label](https://docs.webstudio.is/university/core-components/label.md) - Associated labels
* [Form](https://docs.webstudio.is/university/core-components/form.md) - Form container


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.webstudio.is/university/core-components/checkbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
