---
metaTitle: Checkbox component | AwesCode UI
meta:
  - name: description
    content: The <AwCheckbox /> component is used to render Checkbox - UI Vue component for AwesCode UI.
title: Checkbox
---

# Checkbox

**Category:** Atom | **Import:** Global

The `AwCheckbox` component is a styled checkbox input with label support and error handling.

## Overview

`AwCheckbox` provides a checkbox input with consistent styling, label support, and error states. It supports both single checkboxes and checkbox groups (when used with arrays).

## Usage

### Basic Example

```markup
<AwCheckbox v-model="checked" label="Accept terms" />
```

### With Custom Value

```markup
<AwCheckbox 
    v-model="selected" 
    value="option1" 
    label="Option 1" 
/>
```

### Checkbox Group

```markup
<AwCheckbox 
    v-model="selectedItems" 
    value="item1" 
    label="Item 1" 
/>
<AwCheckbox 
    v-model="selectedItems" 
    value="item2" 
    label="Item 2" 
/>
```

### With Error

```markup
<AwCheckbox 
    v-model="checked" 
    label="Required field"
    :error="errorMessage"
/>
```

### Partial State

```markup
<AwCheckbox 
    v-model="selectedItems" 
    value="item1" 
    label="Item 1"
    :partial="isPartial"
/>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| value | Value emitted when checked | `String` / `Number` / `Boolean` / `Object` | `false` | `'on'` |
| checked | Checked state (boolean, number, or array for groups) | `Array` / `Boolean` / `Number` | `false` | `false` |
| label | Label text displayed next to checkbox | `String` | `false` | `''` |
| partial | Show partial/indeterminate state | `Boolean` | `false` | `false` |

All standard HTML checkbox attributes are supported via `$attrs` (e.g., `disabled`, `required`).

Inherits props from `FieldMixin` and `ErrorMixin` for additional field and error handling functionality.

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Custom checkbox element | `{ id, checked, onChange, setError, value }` | Default checkbox input |
| label | Custom label content | `{ label, value, isChecked }` | Label text |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| change | `value` | Emitted when checkbox state changes |

## Component Behavior

### V-Model Implementation

`AwCheckbox` uses a custom v-model configuration:

```javascript
model: {
  prop: 'checked',
  event: 'change'
}
```

This means:
- `v-model="value"` is equivalent to `:checked="value" @change="value = $event"`
- The `checked` prop receives the current state
- The `change` event emits the new state

**Single Checkbox (Boolean):**
```vue
<template>
  <AwCheckbox v-model="accepted" label="I accept" />
</template>

<script>
export default {
  data() {
    return {
      accepted: false // Boolean value
    }
  }
}
</script>
```

**Checkbox Group (Array):**
```vue
<template>
  <AwCheckbox v-model="selected" value="option1" label="Option 1" />
  <AwCheckbox v-model="selected" value="option2" label="Option 2" />
  <AwCheckbox v-model="selected" value="option3" label="Option 3" />
</template>

<script>
export default {
  data() {
    return {
      selected: [] // Array of selected values
    }
  }
}
</script>
```

When `checked` is an array, the component automatically:
- Adds `value` to the array when checked
- Removes `value` from the array when unchecked
- Maintains the immutability of the array (returns new arrays)

### Label Usage

The component provides two ways to add a label:

**Via Label Prop (Recommended):**
```markup
<AwCheckbox v-model="checked" label="Accept terms" />
```
- Simple text label
- Proper `for` attribute linking
- Automatic styling

**Via Label Slot (Advanced):**
```markup
<AwCheckbox v-model="checked">
  <template #label="{ label, value, isChecked }">
    <span :class="{ 'font-bold': isChecked }">{{ label }}</span>
  </template>
</AwCheckbox>
```
- Custom label rendering
- Access to component state
- Full control over styling

**Note:** The default slot is for completely custom checkbox rendering, not for labels. Use the `label` prop or `label` slot for labels.

### Value Handling

The `value` prop determines what gets emitted when the checkbox is checked:

**Default (String):**
```markup
<AwCheckbox v-model="checked" />
<!-- Emits: 'on' when checked -->
```

**Custom String:**
```markup
<AwCheckbox v-model="items" value="item1" />
<!-- Emits: 'item1' when checked -->
```

**Number:**
```markup
<AwCheckbox v-model="items" :value="42" />
<!-- Emits: 42 when checked -->
```

**Object:**
```markup
<AwCheckbox v-model="items" :value="{ id: 1, name: 'Item' }" />
<!-- Emits: the object when checked -->
```

### Partial/Indeterminate State

The `partial` prop shows a partial/indeterminate state:
```markup
<AwCheckbox
  v-model="selectAll"
  :partial="someSelected && !allSelected"
  label="Select All"
/>
```

Common use case: "Select All" checkbox in a list:
- `partial: false` - None or all selected (shows check or empty)
- `partial: true` - Some selected (shows indeterminate dash)

### Error Handling

Inherits error management from `ErrorMixin`:

```vue
<template>
  <AwCheckbox
    v-model="accepted"
    label="I accept terms"
    :error="error"
  />
</template>

<script>
export default {
  data() {
    return {
      accepted: false,
      error: ''
    }
  },
  methods: {
    validate() {
      if (!this.accepted) {
        this.error = 'You must accept the terms'
      }
    }
  }
}
</script>
```

Features:
- Error displayed via tooltip on hover
- Adds `has-error` class for styling
- Error clears automatically when state changes
- Error text shown in tooltip

### Field States

CSS classes applied based on component state:
- `is-checkbox` - Always present for checkbox type
- `has-error` - When error is present
- `fb-field` - When using default slot (custom rendering)

## Related Components

- `AwSwitcher` - Toggle switch component
- `AwRadio` - Radio button component
- `AwInput` - Text input component

## Notes

- **Import Method:** Global - Available as atom component
- Uses v-model with `checked` prop and `change` event
- Supports checkbox groups when `checked` is an array
- Automatically manages array when used in groups
- Supports partial/indeterminate state
- Extends field and error mixins for label and error handling
- Value can be any type (string, number, boolean, object)