Components

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 prop to set the Checkbox to an indeterminate state.

indeterminate

<template>
  <UCheckbox indeterminate />
</template>

Indeterminate Icon

Use the indeterminate-icon prop to customize the indeterminate icon. Defaults to i-heroicons-minus-20-solid.

indeterminate

indeterminateIcon

<template>
  <UCheckbox indeterminate indeterminate-icon="i-heroicons-plus-20-solid" />
</template>

You can customize this icon globally in your app.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-heroicons-check-20-solid.

icon

Check me

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

You can customize this icon globally in your app.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="gray" 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
`modelValue`		`boolean`
`label`		`string`
`description`		`string`
`color`	`primary`	`"error" \| "primary" \| "red" \| "orange" \| "amber" \| "yellow" \| "lime" \| "green" \| "emerald" \| "teal" \| "cyan" \| "sky" \| "blue" \| "indigo" \| "violet" \| "purple" \| "fuchsia" \| "pink" \| "rose" \| "gray"`
`size`	`md`	`"md" \| "xs" \| "sm" \| "lg" \| "xl"`
`icon`	`appConfig.ui.icons.check`	`string` The icon displayed when checked.
`indeterminate`		`boolean`
`indeterminateIcon`	`appConfig.ui.icons.minus`	`string` The icon displayed when the checkbox is indeterminate.
`defaultValue`		`boolean` The checked state of the checkbox when it is initially rendered. Use when you do not need to control its checked state.
`disabled`		`boolean` When `true`, prevents the user from interacting with the checkbox
`required`		`boolean` When `true`, indicates that the user must check the checkbox before the owning form can be submitted.
`name`		`string` The name of the checkbox. Submitted with its owning form as part of a name/value pair.
`value`	`"on"`	`string` The value given as data when submitted with a `name`.
`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`	`[payload: boolean]`

Theme

app.config.ts

export default defineAppConfig({
  ui: {
    checkbox: {
      slots: {
        root: 'relative flex items-start',
        base: 'shrink-0 flex items-center justify-center rounded text-white dark:text-gray-900 ring ring-inset ring-gray-300 dark:ring-gray-700 focus:outline-none 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-gray-700 dark:text-gray-200',
        description: 'text-gray-500 dark:text-gray-400'
      },
      variants: {
        color: {
          primary: 'focus-visible:outline-primary-500 dark:focus-visible:outline-primary-400',
          error: 'focus-visible:outline-error-500 dark:focus-visible:outline-error-400',
          red: 'focus-visible:outline-red-500 dark:focus-visible:outline-red-400',
          orange: 'focus-visible:outline-orange-500 dark:focus-visible:outline-orange-400',
          amber: 'focus-visible:outline-amber-500 dark:focus-visible:outline-amber-400',
          yellow: 'focus-visible:outline-yellow-500 dark:focus-visible:outline-yellow-400',
          lime: 'focus-visible:outline-lime-500 dark:focus-visible:outline-lime-400',
          green: 'focus-visible:outline-green-500 dark:focus-visible:outline-green-400',
          emerald: 'focus-visible:outline-emerald-500 dark:focus-visible:outline-emerald-400',
          teal: 'focus-visible:outline-teal-500 dark:focus-visible:outline-teal-400',
          cyan: 'focus-visible:outline-cyan-500 dark:focus-visible:outline-cyan-400',
          sky: 'focus-visible:outline-sky-500 dark:focus-visible:outline-sky-400',
          blue: 'focus-visible:outline-blue-500 dark:focus-visible:outline-blue-400',
          indigo: 'focus-visible:outline-indigo-500 dark:focus-visible:outline-indigo-400',
          violet: 'focus-visible:outline-violet-500 dark:focus-visible:outline-violet-400',
          purple: 'focus-visible:outline-purple-500 dark:focus-visible:outline-purple-400',
          fuchsia: 'focus-visible:outline-fuchsia-500 dark:focus-visible:outline-fuchsia-400',
          pink: 'focus-visible:outline-pink-500 dark:focus-visible:outline-pink-400',
          rose: 'focus-visible:outline-rose-500 dark:focus-visible:outline-rose-400',
          gray: 'focus-visible:outline-gray-900 dark:focus-visible:outline-white'
        },
        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-error-500 dark:after:text-error-400"
          }
        },
        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-primary-500 dark:ring-primary-400 bg-primary-500 dark:bg-primary-400'
        },
        {
          color: 'gray',
          checked: true,
          class: 'ring-2 ring-gray-900 dark:ring-white bg-gray-900 dark:bg-white'
        }
      ],
      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 support.

Chip

An indicator of a numeric value or a state.