---
title: "Checkbox"
description: "An input element to toggle between checked and unchecked states."
canonical_url: "https://vinicunca.dev/pohon/components/checkbox"
---
# Checkbox

> An input element to toggle between checked and unchecked states.

## Usage

Use the `v-model` directive to control the checked state of the Checkbox.

```vue
<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <PCheckbox v-model="value" />
</template>
```

Use the `default-value` prop to set the initial value when you do not need to control its state.

```vue
<template>
  <PCheckbox default-value />
</template>
```

### Indeterminate

Use the `indeterminate` value in the `v-model` directive or `default-value` prop to set the Checkbox to an [indeterminate state](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/checkbox#indeterminate_state_checkboxes).

```vue
<template>
  <PCheckbox default-value="indeterminate" />
</template>
```

### Indeterminate Icon

Use the `indeterminate-icon` prop to customize the indeterminate icon. Defaults to `i-lucide-minus`.

```vue
<template>
  <PCheckbox default-value="indeterminate" indeterminate-icon="i-lucide-plus" />
</template>
```

**Nuxt:**

> [!TIP]
> See: /pohon/getting-started/integrations/icons/nuxt#theme
> 
> You can customize this icon globally in your `app.config.ts` under `ui.icons.minus` key.

**Vue:**

> [!TIP]
> See: /pohon/getting-started/integrations/icons/vue#theme
> 
> You can customize this icon globally in your `vite.config.ts` under `ui.icons.minus` key.

### Label

Use the `label` prop to set the label of the Checkbox.

```vue
<template>
  <PCheckbox label="Check me" />
</template>
```

When using the `required` prop, an asterisk is added next to the label.

```vue
<template>
  <PCheckbox required label="Check me" />
</template>
```

### Description

Use the `description` prop to set the description of the Checkbox.

```vue
<template>
  <PCheckbox label="Check me" description="This is a checkbox." />
</template>
```

### Icon

Use the `icon` prop to set the icon of the Checkbox when it is checked. Defaults to `i-lucide-check`.

```vue
<template>
  <PCheckbox icon="i-lucide-heart" default-value label="Check me" />
</template>
```

**Nuxt:**

> [!TIP]
> See: /pohon/getting-started/integrations/icons/nuxt#theme
> 
> You can customize this icon globally in your `app.config.ts` under `ui.icons.check` key.

**Vue:**

> [!TIP]
> See: /pohon/getting-started/integrations/icons/vue#theme
> 
> You can customize this icon globally in your `vite.config.ts` under `ui.icons.check` key.

### Color

Use the `color` prop to change the color of the Checkbox.

```vue
<template>
  <PCheckbox color="neutral" default-value label="Check me" />
</template>
```

### Variant

Use the `variant` prop to change the variant of the Checkbox.

```vue
<template>
  <PCheckbox color="primary" variant="card" default-value label="Check me" />
</template>
```

### Size

Use the `size` prop to change the size of the Checkbox.

```vue
<template>
  <PCheckbox size="xl" variant="list" default-value label="Check me" />
</template>
```

### Indicator

Use the `indicator` prop to change the position or hide the indicator. Defaults to `start`.

> [!NOTE]
> 
> When `indicator` is `hidden`, the icon is displayed above the label instead.

```vue
<template>
  <PCheckbox indicator="hidden" variant="card" icon="i-lucide-heart" default-value label="Check me" />
</template>
```

### Disabled

Use the `disabled` prop to disable the Checkbox.

```vue
<template>
  <PCheckbox disabled label="Check me" />
</template>
```

## API

### Props

```ts
/**
 * Props for the Checkbox component
 */
interface CheckboxProps {
}
```

> [!NOTE]
> See: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/button#attributes
> 
> This component also supports all native `<button>` HTML attributes.

### Slots

```ts
/**
 * Slots for the Checkbox component
 */
interface CheckboxSlots {
}
```

### Emits

No events available for this component.

## Theme

```ts [app.config.ts]
export default defineAppConfig({
  ui: {
    checkbox: {
      slots: {
        root: 'relative flex items-start',
        container: 'flex items-center',
        base: 'rounded-sm ring ring-inset ring-border-accented overflow-hidden focus-visible:outline-none',
        indicator: 'flex items-center justify-center size-full',
        icon: 'shrink-0',
        wrapper: 'w-full',
        label: 'block font-500 color-text',
        description: 'color-text-muted'
      },
      variants: {
        color: {
          primary: {
            indicator: 'bg-primary color-primary-foreground'
          },
          secondary: {
            indicator: 'bg-secondary color-secondary-foreground'
          },
          success: {
            indicator: 'bg-success color-success-foreground'
          },
          info: {
            indicator: 'bg-info color-info-foreground'
          },
          warning: {
            indicator: 'bg-warning color-warning-foreground'
          },
          error: {
            indicator: 'bg-error color-error-foreground'
          },
          neutral: {
            indicator: 'bg-background-inverted color-text-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: [
              'border border-border rounded-lg hover:[&:not(:has(:disabled,[aria-disabled=true],:focus-visible,[data-state=checked]))]:bg-background-elevated/50',
              'transition-colors'
            ]
          }
        },
        indicator: {
          start: {
            root: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            root: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'flex flex-col items-center gap-1 text-center'
          }
        },
        size: {
          xs: {
            base: 'size-3',
            icon: 'size-2.5',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'size-3.5',
            icon: 'size-3',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          md: {
            base: 'size-4',
            icon: 'size-3.5',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'size-4.5',
            icon: 'size-4',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'size-5',
            icon: 'size-4.5',
            container: 'h-6',
            wrapper: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:color-error after:ms-0.5 after:content-['*']"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        },
        highlight: {
          true: '',
          false: ''
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          indicator: 'hidden',
          class: {
            container: 'h-auto'
          }
        },
        {
          variant: 'card',
          highlight: false,
          class: {
            root: 'hover:[&:not(:has(:disabled,[aria-disabled=true],:focus-visible,[data-state=checked]))]:border-border-accented'
          }
        },
        {
          size: 'xs',
          indicator: 'hidden',
          class: {
            icon: 'size-3'
          }
        },
        {
          size: 'sm',
          indicator: 'hidden',
          class: {
            icon: 'size-3.5'
          }
        },
        {
          size: 'md',
          indicator: 'hidden',
          class: {
            icon: 'size-4'
          }
        },
        {
          size: 'lg',
          indicator: 'hidden',
          class: {
            icon: 'size-4.5'
          }
        },
        {
          size: 'xl',
          indicator: 'hidden',
          class: {
            icon: 'size-5'
          }
        },
        {
          size: 'xs',
          variant: 'card',
          class: {
            root: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'card',
          class: {
            root: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'card',
          class: {
            root: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'card',
          class: {
            root: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'card',
          class: {
            root: 'p-4.5'
          }
        },
        {
          color: 'primary',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-primary/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-primary'
          }
        },
        {
          color: 'secondary',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-secondary/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-secondary'
          }
        },
        {
          color: 'success',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-success/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-success'
          }
        },
        {
          color: 'info',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-info/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-info'
          }
        },
        {
          color: 'warning',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-warning/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-warning'
          }
        },
        {
          color: 'error',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-error/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-error'
          }
        },
        {
          color: 'neutral',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-inverted/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'outline-primary/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-primary has-focus-visible:z-1'
          }
        },
        {
          color: 'secondary',
          variant: 'card',
          class: {
            root: 'outline-secondary/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-secondary has-focus-visible:z-1'
          }
        },
        {
          color: 'success',
          variant: 'card',
          class: {
            root: 'outline-success/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-success has-focus-visible:z-1'
          }
        },
        {
          color: 'info',
          variant: 'card',
          class: {
            root: 'outline-info/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-info has-focus-visible:z-1'
          }
        },
        {
          color: 'warning',
          variant: 'card',
          class: {
            root: 'outline-warning/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-warning has-focus-visible:z-1'
          }
        },
        {
          color: 'error',
          variant: 'card',
          class: {
            root: 'outline-error/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-error has-focus-visible:z-1'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-inverted has-focus-visible:z-1'
          }
        },
        {
          color: 'primary',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-primary/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-primary has-focus-visible:z-1'
          }
        },
        {
          color: 'secondary',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-secondary/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-secondary has-focus-visible:z-1'
          }
        },
        {
          color: 'success',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-success/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-success has-focus-visible:z-1'
          }
        },
        {
          color: 'info',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-info/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-info has-focus-visible:z-1'
          }
        },
        {
          color: 'warning',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-warning/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-warning has-focus-visible:z-1'
          }
        },
        {
          color: 'error',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-error/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-error has-focus-visible:z-1'
          }
        },
        {
          color: 'neutral',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 has-focus-visible:[&:not(:has(:disabled,[aria-disabled=true]))]:border-inverted has-focus-visible:z-1'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-primary/50 has-data-[state=checked]:bg-primary/10'
          }
        },
        {
          color: 'secondary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-secondary/50 has-data-[state=checked]:bg-secondary/10'
          }
        },
        {
          color: 'success',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-success/50 has-data-[state=checked]:bg-success/10'
          }
        },
        {
          color: 'info',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-info/50 has-data-[state=checked]:bg-info/10'
          }
        },
        {
          color: 'warning',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-warning/50 has-data-[state=checked]:bg-warning/10'
          }
        },
        {
          color: 'error',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-error/50 has-data-[state=checked]:bg-error/10'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-border-inverted/50 has-data-[state=checked]:bg-background-elevated'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-primary [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-primary'
          }
        },
        {
          color: 'secondary',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-secondary [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-secondary'
          }
        },
        {
          color: 'success',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-success [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-success'
          }
        },
        {
          color: 'info',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-info [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-info'
          }
        },
        {
          color: 'warning',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-warning [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-warning'
          }
        },
        {
          color: 'error',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-error [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-error'
          }
        },
        {
          color: 'neutral',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: '[&:not(:has(:disabled,[aria-disabled=true]))]:border-border-inverted [&:not(:has(:disabled,[aria-disabled=true])):has([data-state=checked])]:border-border-inverted'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'secondary',
          highlight: true,
          class: {
            base: 'ring-secondary'
          }
        },
        {
          color: 'success',
          highlight: true,
          class: {
            base: 'ring-success'
          }
        },
        {
          color: 'info',
          highlight: true,
          class: {
            base: 'ring-info'
          }
        },
        {
          color: 'warning',
          highlight: true,
          class: {
            base: 'ring-warning'
          }
        },
        {
          color: 'error',
          highlight: true,
          class: {
            base: 'ring-error'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-border-inverted'
          }
        }
      ],
      defaultVariants: {
        highlight: false,
        size: 'md',
        color: 'primary',
        variant: 'list',
        indicator: 'start'
      }
    }
  }
})
```

## Changelog

See commit history for [component](https://github.com/vinicunca/pohon/commits/main/src/runtime/components/Checkbox.vue) and [theme](https://github.com/vinicunca/pohon/commits/main/src/theme/checkbox.ts).

---

- [Checkbox](https://vinicunca.dev/akar/components/checkbox)
- [GitHub](https://github.com/vinicunca/pohon/blob/main/src/runtime/components/Checkbox.vue)


## Sitemap

See the full [sitemap](https://vinicunca.dev/sitemap.md) for all pages.