# Checkbox

A control that allows the user to toggle between checked and not checked.

## Import

```
Copyts
import { Checkbox } from "@kobalte/core/checkbox";
// or
import { Root, Input, ... } from "@kobalte/core/checkbox";
// or (deprecated)
import { Checkbox } from "@kobalte/core";
```

```
Copyts
import { Checkbox } from "@kobalte/core/checkbox";
// or
import { Root, Input, ... } from "@kobalte/core/checkbox";
// or (deprecated)
import { Checkbox } from "@kobalte/core";
```

## Features

- Built with a native HTML `<input>` element, which is visually hidden to allow custom styling.
- Syncs with form reset events.
- Labeling support for assistive technology.
- Support for description and error message help text linked to the input via ARIA.
- Can be controlled or uncontrolled.

## Anatomy

The checkbox consists of:

- **Checkbox:** The root container for a checkbox.
- **Checkbox.Input:** The native html input that is visually hidden in the checkbox.
- **Checkbox.Control:** The element that visually represents a checkbox.
- **Checkbox.Indicator:** The visual indicator rendered when the checkbox is in a checked or indeterminate state.
- **Checkbox.Label:** The label that gives the user information on the checkbox.
- **Checkbox.Description**: The description that gives the user more information on the checkbox.
- **Checkbox.ErrorMessage**: The error message that gives the user information about how to fix a validation error on the checkbox.

```
Copytsx
<Checkbox>
	<Checkbox.Input />
	<Checkbox.Control>
		<Checkbox.Indicator />
	</Checkbox.Control>
	<Checkbox.Label />
	<Checkbox.Description />
	<Checkbox.ErrorMessage />
</Checkbox>
```

```
Copytsx
<Checkbox>
	<Checkbox.Input />
	<Checkbox.Control>
		<Checkbox.Indicator />
	</Checkbox.Control>
	<Checkbox.Label />
	<Checkbox.Description />
	<Checkbox.ErrorMessage />
</Checkbox>
```

## Example

Subscribe

index.tsxstyle.css

```
Copytsx
import { Checkbox } from "@kobalte/core/checkbox";
import { CheckIcon } from "some-icon-library";
import "./style.css";

function App() {
  return (
    <Checkbox class="checkbox">
      <Checkbox.Input class="checkbox__input" />
      <Checkbox.Control class="checkbox__control">
        <Checkbox.Indicator>
          <CheckIcon />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class="checkbox__label">Subscribe</Checkbox.Label>
    </Checkbox>
  );
}
```

```
Copytsx
import { Checkbox } from "@kobalte/core/checkbox";
import { CheckIcon } from "some-icon-library";
import "./style.css";

function App() {
  return (
    <Checkbox class="checkbox">
      <Checkbox.Input class="checkbox__input" />
      <Checkbox.Control class="checkbox__control">
        <Checkbox.Indicator>
          <CheckIcon />
        </Checkbox.Indicator>
      </Checkbox.Control>
      <Checkbox.Label class="checkbox__label">Subscribe</Checkbox.Label>
    </Checkbox>
  );
}
```

## Usage

### Default checked

An initial, uncontrolled value can be provided using the `defaultChecked` prop.

Check

Subscribe

```
Copytsx
<Checkbox defaultChecked>...</Checkbox>
```

```
Copytsx
<Checkbox defaultChecked>...</Checkbox>
```

### Controlled checked

The `checked` prop can be used to make the checked state controlled. The `onChange` event is fired when the user presses the checkbox, and receives the new value.

Subscribe

You are unsubscribed.

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<>
			<Checkbox checked={checked()} onChange={setChecked}>
				...
			</Checkbox>
			<p>You are {checked() ? "subscribed" : "unsubscribed"}.</p>
		</>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ControlledExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<>
			<Checkbox checked={checked()} onChange={setChecked}>
				...
			</Checkbox>
			<p>You are {checked() ? "subscribed" : "unsubscribed"}.</p>
		</>
	);
}
```

### Description

The `Checkbox.Description` component can be used to associate additional help text with a checkbox.

Subscribe

You will receive our weekly newsletter.

```
Copytsx
<Checkbox>
	<Checkbox.Input />
	<Checkbox.Control>
		<Checkbox.Indicator>
			<CheckIcon />
		</Checkbox.Indicator>
	</Checkbox.Control>
	<Checkbox.Label>Subscribe</Checkbox.Label>
	<Checkbox.Description>You will receive our weekly newsletter.</Checkbox.Description>
</Checkbox>
```

```
Copytsx
<Checkbox>
	<Checkbox.Input />
	<Checkbox.Control>
		<Checkbox.Indicator>
			<CheckIcon />
		</Checkbox.Indicator>
	</Checkbox.Control>
	<Checkbox.Label>Subscribe</Checkbox.Label>
	<Checkbox.Description>You will receive our weekly newsletter.</Checkbox.Description>
</Checkbox>
```

### Error message

The `Checkbox.ErrorMessage` component can be used to help the user fix a validation error. It should be combined with the `validationState` prop to semantically mark the checkbox as invalid for assistive technologies.

By default, it will render only when the `validationState` prop is set to `invalid`, use the `forceMount` prop to always render the error message (ex: for usage with animation libraries).

Subscribe

You must agree to our Terms and Conditions.

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<Checkbox
			checked={checked()}
			onChange={setChecked}
			validationState={!checked() ? "invalid" : "valid"}
		>
			<Checkbox.Input />
			<Checkbox.Control>
				<Checkbox.Indicator>
					<CheckIcon />
				</Checkbox.Indicator>
			</Checkbox.Control>
			<Checkbox.Label>Agree</Checkbox.Label>
			<Checkbox.ErrorMessage>You must agree to our Terms and Conditions.</Checkbox.ErrorMessage>
		</Checkbox>
	);
}
```

```
Copytsx
import { createSignal } from "solid-js";

function ErrorMessageExample() {
	const [checked, setChecked] = createSignal(false);

	return (
		<Checkbox
			checked={checked()}
			onChange={setChecked}
			validationState={!checked() ? "invalid" : "valid"}
		>
			<Checkbox.Input />
			<Checkbox.Control>
				<Checkbox.Indicator>
					<CheckIcon />
				</Checkbox.Indicator>
			</Checkbox.Control>
			<Checkbox.Label>Agree</Checkbox.Label>
			<Checkbox.ErrorMessage>You must agree to our Terms and Conditions.</Checkbox.ErrorMessage>
		</Checkbox>
	);
}
```

### HTML forms

The `name` and `value` props can be used for integration with HTML forms.

Subscribe

ResetSubmit

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};

	return (
		<form onSubmit={onSubmit}>
			<Checkbox name="newsletter" value="subscribe">
				...
			</Checkbox>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

```
Copytsx
function HTMLFormExample() {
	const onSubmit = (e: SubmitEvent) => {
		// handle form submission.
	};

	return (
		<form onSubmit={onSubmit}>
			<Checkbox name="newsletter" value="subscribe">
				...
			</Checkbox>
			<div>
				<button type="reset">Reset</button>
				<button type="submit">Submit</button>
			</div>
		</form>
	);
}
```

## API Reference

### Checkbox

`Checkbox` is equivalent to the `Root` import from `@kobalte/core/checkbox` (and deprecated `Checkbox.Root`).

| Prop | Description |
| --- | --- |
| checked | `boolean`<br> The controlled checked state of the checkbox. |
| defaultChecked | `boolean`<br> The default checked state when initially rendered. Useful when you do not need to control the checked state. |
| onChange | `(checked: boolean) => void`<br> Event handler called when the checked state of the checkbox changes. |
| indeterminate | `boolean`<br> Whether the checkbox is in an indeterminate state. |
| name | `string`<br> The name of the checkbox, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). |
| value | `string`<br> The value of the checkbox, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue). |
| validationState | `'valid' | 'invalid'`<br> Whether the checkbox should display its "valid" or "invalid" visual styling. |
| required | `boolean`<br> Whether the user must check the checkbox before the owning form can be submitted. |
| disabled | `boolean`<br> Whether the checkbox is disabled. |
| readOnly | `boolean`<br> Whether the checkbox can be checked but not changed by the user. |
| children | `JSX.Element | (state: CheckboxState) => JSX.Element`<br> The children of the checkbox. Can be a `JSX.Element` or a _render prop_ for having access to the internal state. |

| Render Prop | Description |
| --- | --- |
| checked | `Accessor<boolean>`<br> Whether the checkbox is checked or not. |
| indeterminate | `Accessor<boolean>`<br> Whether the checkbox is in an indeterminate state. |

| Data attribute | Description |
| --- | --- |
| data-valid | Present when the checkbox is valid according to the validation rules. |
| data-invalid | Present when the checkbox is invalid according to the validation rules. |
| data-required | Present when the checkbox is required. |
| data-disabled | Present when the checkbox is disabled. |
| data-readonly | Present when the checkbox is read only. |
| data-checked | Present when the checkbox is checked. |
| data-indeterminate | Present when the checkbox is in an indeterminate state. |

`Checkbox.Input`, `Checkbox.Control`, `Checkbox.Indicator`, `Checkbox.Label`, `Checkbox.Description` and `Checkbox.ErrorMessage` share the same data-attributes.

### Checkbox.Indicator

| Prop | Description |
| --- | --- |
| forceMount | `boolean`<br> Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries. |

### Checkbox.ErrorMessage

| Prop | Description |
| --- | --- |
| forceMount | `boolean`<br> Used to force mounting when more control is needed. Useful when controlling animation with SolidJS animation libraries. |

## Rendered elements

| Component | Default rendered element |
| --- | --- |
| `Checkbox` | `div` |
| `Checkbox.Input` | `input` |
| `Checkbox.Control` | `div` |
| `Checkbox.Indicator` | `div` |
| `Checkbox.Label` | `label` |
| `Checkbox.Description` | `div` |
| `Checkbox.ErrorMessage` | `div` |

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `Space` | Toggles the checkbox on and off. |

Previous[←Button](https://kobalte.dev/docs/core/components/button)Next[Collapsible→](https://kobalte.dev/docs/core/components/collapsible)