v3.0.0-alpha.9

Checkbox

CheckboxGitHub
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.

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

Indeterminate Icon

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

<template>
  <UCheckbox indeterminate indeterminate-icon="i-lucide-plus" />
</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.

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

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

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

Description

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

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.

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

Color

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

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

Size

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

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

Disabled

Use the disabled prop to disable the Checkbox.

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

API

Props

Prop Default Type
modelValue

boolean

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.

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.

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.

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.

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-[var(--ui-radius)] text-[var(--ui-bg)] ring ring-inset ring-[var(--ui-border-accented)] 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-[var(--ui-text)]',
        description: 'text-[var(--ui-text-muted)]'
      },
      variants: {
        color: {
          primary: 'focus-visible:outline-[var(--ui-primary)]',
          secondary: 'focus-visible:outline-[var(--ui-secondary)]',
          success: 'focus-visible:outline-[var(--ui-success)]',
          info: 'focus-visible:outline-[var(--ui-info)]',
          warning: 'focus-visible:outline-[var(--ui-warning)]',
          error: 'focus-visible:outline-[var(--ui-error)]',
          neutral: 'focus-visible:outline-[var(--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-[var(--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-[var(--ui-primary)] bg-[var(--ui-primary)]'
        },
        {
          color: 'neutral',
          checked: true,
          class: 'ring-2 ring-[var(--ui-border-inverted)] bg-[var(--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.