# Checkbox

> A checkbox, alone or in a group.

## Examples

### Basic

```vue
<script setup lang="ts">
const accepted = ref(false);
</script>

<template>
  <div class="demo-stack">
    <UiCheckbox v-model="accepted" label="Accept the terms" />
    <UiCheckbox :model-value="true" label="Disabled" disabled />
  </div>
</template>
```

### Group

Bind several checkboxes to one array: each adds its `value` when checked.

```vue
<script setup lang="ts">
const toppings = ref(["cheese"]);
</script>

<template>
  <div class="demo-stack demo-field">
    <UiCheckbox v-model="toppings" value="cheese" label="Cheese" />
    <UiCheckbox v-model="toppings" value="olives" label="Olives" />
    <UiCheckbox v-model="toppings" value="basil" label="Basil" />
    <p class="demo-note">Selected: {{ toppings.join(", ") || "none" }}</p>
  </div>
</template>
```

### Indeterminate

```vue
<script setup lang="ts">
const files = ref(["a.txt"]);
const all = ["a.txt", "b.txt", "c.txt"];

const allSelected = computed({
  get: () => files.value.length === all.length,
  set: (checked) => (files.value = checked ? [...all] : []),
});
const someSelected = computed(() => files.value.length > 0 && !allSelected.value);
</script>

<template>
  <div class="demo-stack">
    <UiCheckbox v-model="allSelected" :indeterminate="someSelected" label="Select all" />
    <div class="demo-stack demo-indent">
      <UiCheckbox v-for="file in all" :key="file" v-model="files" :value="file" :label="file" />
    </div>
  </div>
</template>
```

### Hint and error

Shown under the label and read as its description.

```vue
<script setup lang="ts">
const accepted = ref(false);
const tried = ref(false);
</script>

<template>
  <div class="demo-stack">
    <UiCheckbox
      v-model="accepted"
      label="Accept the terms"
      hint="Required to create an account."
      :error="tried && !accepted ? 'Accept the terms to continue' : undefined"
    />
    <UiButton size="small" @click="tried = true">Create account</UiButton>
  </div>
</template>
```

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | — | Text next to the box. The default slot overrides it. |
| `disabled` | `boolean` | `false` | Disables the checkbox. |
| `indeterminate` | `boolean` | `false` | Shows the mixed state, e.g. for a "select all" with some rows picked. |
| `value` | `string \| number` | — | With an array `v-model`, this value is added/removed when toggled. |
| `hint` | `string` | — | Help text under the checkbox, announced as its description. |
| `error` | `string \| boolean` | — | `true` marks it invalid; a string also shows it as the message, replacing the hint. |
| `id` | `string` | — | Id for the input; generated with `useId()` when omitted. |
| `modelValue` | `boolean \| (string \| number)[]` | — | Checked state, or with an array, the checked `value`s. |

| Event | Payload | Description |
| --- | --- | --- |
| `update:modelValue` | `[value: boolean \| (string \| number)[] \| undefined]` | `v-model:modelValue` update. |

| Slot | Props | Description |
| --- | --- | --- |
| `default` | — | Label content, replacing `label`. |
| `indicator` | — | Inside `checkbox-control`, e.g. a check icon. |

## Styling

- Parts (`[data-part="…"]`): `checkbox`, `checkbox-input`, `checkbox-control`, `checkbox-label`, `field-message`
- State attributes: `data-checkbox-disabled`, `data-checkbox-error`, `data-field-tone`

## Keyboard

| Keys    | Action |
| ------- | ------ |
| `Space` | Toggle |

## Accessibility

- It's a native `<input type="checkbox">`, so it submits with forms and works with any label.