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.

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

<template>
  <UCheckbox v-model="value" />
</template>

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

<template>
  <UCheckbox 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.

<template>
  <UCheckbox default-value="indeterminate" />
</template>

Indeterminate Icon

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

indeterminateIcon

<template>
  <UCheckbox default-value="indeterminate" indeterminate-icon="i-lucide-plus" />
</template>

You can customize this icon globally in your app.config.ts under ui.icons.minus key.

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.

label

Check me

<template>
  <UCheckbox label="Check me" />
</template>

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

required

Check me

<template>
  <UCheckbox required label="Check me" />
</template>

Description

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

description

Check me

This is a checkbox.

<template>
  <UCheckbox 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.

icon

Check me

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

You can customize this icon globally in your app.config.ts under ui.icons.check key.

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.

color

Check me

<template>
  <UCheckbox color="neutral" default-value label="Check me" />
</template>

Size

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

size

Check me

<template>
  <UCheckbox size="xl" default-value label="Check me" />
</template>

Disabled

Use the disabled prop to disable the Checkbox.

disabled

Check me

<template>
  <UCheckbox disabled label="Check me" />
</template>

API

Props

Prop	Default	Type
`as`	`'div'`	`any` The element or component this component should render as.
`modelValue`		`boolean \| "indeterminate"`
`label`		`string`
`description`		`string`
`color`	`'primary'`	`"error" \| "primary" \| "secondary" \| "success" \| "info" \| "warning" \| "neutral"`
`size`	`'md'`	`"md" \| "xs" \| "sm" \| "lg" \| "xl"`
`icon`	`appConfig.ui.icons.check`	`string` The icon displayed when checked.
`indeterminateIcon`	`appConfig.ui.icons.minus`	`string` The icon displayed when the checkbox is indeterminate.
`defaultValue`		`boolean \| "indeterminate"` The value of the checkbox when it is initially rendered. Use when you do not need to control its value.
`disabled`		`boolean` When `true`, prevents the user from interacting with the checkbox
`name`		`string` The name of the field. Submitted with its owning form as part of a name/value pair.
`value`	`"on"`	`null \| string \| number \| Record<string, any>` The value given as data when submitted with a `name`.
`required`		`boolean` When `true`, indicates that the user must set the value before the owning form can be submitted.
`id`		`string` Id of the element
`ui`		`Partial<{ root: string; base: string; container: string; wrapper: string; icon: string; label: string; description: string; }>`

Slots

Slot	Type
`label`	`{ label?: string \| undefined; }`
`description`	`{ description?: string \| undefined; }`

Emits

Event	Type
`change`	`[payload: Event]`
`update:modelValue`	`[value: boolean \| "indeterminate" \| undefined]`

Theme

app.config.ts

export default defineAppConfig({
  ui: {
    checkbox: {
      slots: {
        root: 'relative flex items-start',
        base: 'shrink-0 flex items-center justify-center rounded-(--ui-radius) text-(--ui-bg) ring ring-inset ring-(--ui-border-accented) focus-visible:outline-2 focus-visible:outline-offset-2',
        container: 'flex items-center',
        wrapper: 'ms-2',
        icon: 'shrink-0 size-full',
        label: 'block font-medium text-(--ui-text)',
        description: 'text-(--ui-text-muted)'
      },
      variants: {
        color: {
          primary: 'focus-visible:outline-(--ui-primary)',
          secondary: 'focus-visible:outline-(--ui-secondary)',
          success: 'focus-visible:outline-(--ui-success)',
          info: 'focus-visible:outline-(--ui-info)',
          warning: 'focus-visible:outline-(--ui-warning)',
          error: 'focus-visible:outline-(--ui-error)',
          neutral: 'focus-visible:outline-(--ui-border-inverted)'
        },
        size: {
          xs: {
            base: 'size-3',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'size-3.5',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          md: {
            base: 'size-4',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'size-4.5',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'size-5',
            container: 'h-6',
            wrapper: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-(--ui-error)"
          }
        },
        disabled: {
          true: {
            base: 'cursor-not-allowed opacity-75',
            label: 'cursor-not-allowed opacity-75',
            description: 'cursor-not-allowed opacity-75'
          }
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          checked: true,
          class: 'ring-2 ring-(--ui-primary) bg-(--ui-primary)'
        },
        {
          color: 'neutral',
          checked: true,
          class: 'ring-2 ring-(--ui-border-inverted) bg-(--ui-bg-inverted)'
        }
      ],
      defaultVariants: {
        size: 'md',
        color: 'primary'
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        checkbox: {
          slots: {
            root: 'relative flex items-start',
            base: 'shrink-0 flex items-center justify-center rounded-(--ui-radius) text-(--ui-bg) ring ring-inset ring-(--ui-border-accented) focus-visible:outline-2 focus-visible:outline-offset-2',
            container: 'flex items-center',
            wrapper: 'ms-2',
            icon: 'shrink-0 size-full',
            label: 'block font-medium text-(--ui-text)',
            description: 'text-(--ui-text-muted)'
          },
          variants: {
            color: {
              primary: 'focus-visible:outline-(--ui-primary)',
              secondary: 'focus-visible:outline-(--ui-secondary)',
              success: 'focus-visible:outline-(--ui-success)',
              info: 'focus-visible:outline-(--ui-info)',
              warning: 'focus-visible:outline-(--ui-warning)',
              error: 'focus-visible:outline-(--ui-error)',
              neutral: 'focus-visible:outline-(--ui-border-inverted)'
            },
            size: {
              xs: {
                base: 'size-3',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              sm: {
                base: 'size-3.5',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              md: {
                base: 'size-4',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              lg: {
                base: 'size-4.5',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              xl: {
                base: 'size-5',
                container: 'h-6',
                wrapper: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-(--ui-error)"
              }
            },
            disabled: {
              true: {
                base: 'cursor-not-allowed opacity-75',
                label: 'cursor-not-allowed opacity-75',
                description: 'cursor-not-allowed opacity-75'
              }
            },
            checked: {
              true: ''
            }
          },
          compoundVariants: [
            {
              color: 'primary',
              checked: true,
              class: 'ring-2 ring-(--ui-primary) bg-(--ui-primary)'
            },
            {
              color: 'neutral',
              checked: true,
              class: 'ring-2 ring-(--ui-border-inverted) bg-(--ui-bg-inverted)'
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary'
          }
        }
      }
    })
  ]
})

Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

Carousel

A carousel with motion and swipe built using Embla.

Chip

An indicator of a numeric value or a state.