# Checkbox (w-checkbox)

## Description

Checkboxes allow users to select one or more options from a number of choices.

Wrap individual checkboxes in a checkbox group.

[Warp component reference](https://warp-ds.github.io/docs/components/checkbox/frameworks/elements)

# Checkbox Styling

The checkbox component provides a comprehensive styling API through CSS custom properties (tokens).

## Styling API

### Label Tokens

Customize the appearance of the label text:

```css
--w-c-checkbox-label-font-size: var(--w-font-size-m);
--w-c-checkbox-label-line-height: var(--w-line-height-m);
```

### Control Tokens

Customize the checkbox control (the box itself):

```css
--w-c-checkbox-control-size: 2rem;
--w-c-checkbox-gap: 8px;
--w-c-checkbox-radius: 4px;
--w-c-checkbox-border-width: 1px;
```

### Color Tokens - Default State

```css
--w-c-checkbox-bg: var(--w-s-color-background);
--w-c-checkbox-border-color: var(--w-s-color-border-strong);
--w-c-checkbox-icon-color: var(--w-s-color-icon-inverted);
```

### Color Tokens - Checked State

```css
--w-c-checkbox-bg-checked: var(--w-s-color-background-primary);
--w-c-checkbox-border-color-checked: var(--w-s-color-border-primary);
--w-c-checkbox-checked-icon: var(--w-icon-toggle-checked);
```

### Color Tokens - Invalid State

```css
--w-c-checkbox-border-color-invalid: var(--w-s-color-border-negative);
--w-c-checkbox-bg-invalid-checked: var(--w-s-color-background-negative);
```

### Color Tokens - Disabled State

```css
--w-c-checkbox-bg-disabled: var(--w-s-color-background-disabled-subtle);
--w-c-checkbox-border-color-disabled: var(--w-s-color-border-disabled);
--w-c-checkbox-bg-disabled-checked: var(--w-s-color-background-disabled);
```

### Focus Tokens

```css
--w-c-checkbox-outline-width: 2px;
--w-c-checkbox-outline-color: var(--w-s-color-border-focus);
--w-c-checkbox-outline-offset: var(--w-outline-offset, 1px);
```

### Animation Tokens

```css
--w-c-checkbox-transition: all 150ms cubic-bezier(0.4, 0, 0.2, 1);
```

## Parts

For advanced styling needs beyond tokens, you can target internal elements using CSS parts:

- `::part(base)` - The wrapper `<label>` element
- `::part(control)` - The visual checkbox control (the box)
- `::part(input)` - The native `<input type="checkbox">` element
- `::part(label)` - The label content wrapper

```css
w-checkbox::part(control) {
  /* Custom styling for the checkbox box */
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

w-checkbox::part(label) {
  /* Custom styling for label text */
  text-transform: uppercase;
}
```

## Example Usage

### Customizing Size

```css
w-checkbox {
  --w-c-checkbox-control-size: 2.4rem;
  --w-c-checkbox-gap: 12px;
}
```

### Customizing Colors

```css
w-checkbox {
  --w-c-checkbox-bg-checked: var(--w-s-color-background-success);
  --w-c-checkbox-border-color-checked: var(--w-s-color-border-success);
}
```

### Customizing Border Radius

```css
w-checkbox {
  --w-c-checkbox-radius: 8px; /* More rounded */
}

/* Or fully rounded */
w-checkbox {
  --w-c-checkbox-radius: 50%;
}
```

### Customizing Focus Outline

```css
w-checkbox {
  --w-c-checkbox-outline-width: 3px;
  --w-c-checkbox-outline-color: var(--w-s-color-border-info);
  --w-c-checkbox-outline-offset: 2px;
}
```

### Disabling Transitions

```css
w-checkbox {
  --w-c-checkbox-transition: none;
}
```

### Using Parts for Advanced Styling

```css
/* Add a subtle shadow to the checkbox */
w-checkbox::part(control) {
  box-shadow: inset 0 1px 3px rgba(0,0,0,0.1);
}

/* Style the label with custom spacing */
w-checkbox::part(label) {
  padding-left: 4px;
  font-weight: 500;
}
```

## Label Content

Unlike textfield/textarea components, checkbox labels accept rich HTML content via the default slot:

```html
<w-checkbox>
  I agree to the <a href="/terms">terms and conditions</a>
</w-checkbox>

<w-checkbox>
  <strong>Important:</strong> Check this box
</w-checkbox>
```

Style the label content directly or use `::part(label)` to target the wrapper.

### `<w-checkbox>` API

#### Properties

| Name | Type | Default | Summary |
|-|-|-|-|
| _computedInvalid (JS only) | `boolean` | `-` | Computed invalid state: combines own invalid with group invalid |
| blur (JS only) | `blur() => void` | `-` | - |
| checkValidity (JS only) | `checkValidity() => boolean` | `-` | Checks whether the checkbox passes constraint validation |
| checked | `boolean` | `false` | Whether the checkbox is checked. |
| click (JS only) | `click() => void` | `-` | - |
| disabled | `boolean` | `false` | Whether the checkbox is disabled. |
| focus (JS only) | `focus(options?: FocusOptions) => void` | `-` | - |
| indeterminate | `boolean` | `false` | Whether the checkbox is visually indeterminate. |
| input (JS only) | `HTMLInputElement` | `-` | - |
| invalid | `boolean` | `false` | Whether the checkbox is visually invalid. |
| name | `string \| undefined` | `-` | The name of the checkbox. |
| reportValidity (JS only) | `reportValidity() => boolean` | `-` | Checks validity and shows the browser's validation message if invalid |
| required | `boolean` | `false` | Whether the checkbox must be checked before form submission. |
| resetFormControl (JS only) | `resetFormControl() => void` | `-` | - |
| shadowRootOptions (JS only) | `object` | `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }` | - |
| validationMessage (JS only) | `string` | `-` | Returns the validation message if the checkbox is invalid, otherwise an empty string |
| validity (JS only) | `ValidityState` | `-` | Returns the validity state of the checkbox |
| value | `string \| null` | `null` | The value submitted when the checkbox is checked. |

#### Property Details

##### _computedInvalid (JS only)

Computed invalid state: combines own invalid with group invalid

- Type: `boolean`
- Default: `-`

##### blur (JS only)



- Type: `blur() => void`
- Default: `-`

##### checkValidity (JS only)

Checks whether the checkbox passes constraint validation

- Type: `checkValidity() => boolean`
- Default: `-`

##### checked

Whether the checkbox is checked.

Checked checkboxes submit their value with form data. The property is reflected to the `checked` attribute.

- Type: `boolean`
- Default: `false`

##### click (JS only)



- Type: `click() => void`
- Default: `-`

##### disabled

Whether the checkbox is disabled.

Disabled checkboxes cannot be focused, changed, or submitted with form data.

- Type: `boolean`
- Default: `false`

##### focus (JS only)



- Type: `focus(options?: FocusOptions) => void`
- Default: `-`

##### indeterminate

Whether the checkbox is visually indeterminate.

Use this for parent options that represent a mixed set of child selections. Clicking the checkbox clears the indeterminate state and sets the checkbox to checked.

- Type: `boolean`
- Default: `false`

##### input (JS only)



- Type: `HTMLInputElement`
- Default: `-`

##### invalid

Whether the checkbox is visually invalid.

Use this to show an externally managed validation error. Required validation also sets the invalid state after the user interacts with the checkbox or tries to submit the form.

- Type: `boolean`
- Default: `false`

##### name

The name of the checkbox.

When the checkbox is checked and belongs to a form, this name is submitted with the checkbox value. If the checkbox is inside a `w-checkbox-group` with a name, the group name is used when the checkbox does not have its own name.

- Type: `string | undefined`
- Default: `-`

##### reportValidity (JS only)

Checks validity and shows the browser's validation message if invalid

- Type: `reportValidity() => boolean`
- Default: `-`

##### required

Whether the checkbox must be checked before form submission.

A required checkbox is invalid until it is checked. For requiring at least one option in a set, use `required` on `w-checkbox-group`.

- Type: `boolean`
- Default: `false`

##### resetFormControl (JS only)



- Type: `resetFormControl() => void`
- Default: `-`

##### shadowRootOptions (JS only)



- Type: `object`
- Default: `{ ...LitElement.shadowRootOptions, delegatesFocus: true, }`

##### validationMessage (JS only)

Returns the validation message if the checkbox is invalid, otherwise an empty string

- Type: `string`
- Default: `-`

##### validity (JS only)

Returns the validity state of the checkbox

- Type: `ValidityState`
- Default: `-`

##### value

The value submitted when the checkbox is checked.

If no value attribute is set, the checkbox defaults to `on`. Unchecked and disabled checkboxes do not submit a value.

- Type: `string | null`
- Default: `null`