Checkbox

复选框GitHub
在选中和未选中状态之间切换的输入元素。

用法

使用v-model指令控制复选框的选中状态。

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

<template>
  <UCheckbox v-model="value" />
</template>
<script setup lang="ts">
import { ref } from 'vue'

const value = ref(true)
</script>

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

当不需要控制其状态时，使用default-value属性设置初始值。

<template>
  <UCheckbox default-value />
</template>

不确定

使用v-model指令或default-value属性中的indeterminate值将复选框设置为indeterminate state。

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

不确定图标

使用indeterminate-icon prop将indeterminate icon.xml自定义为i-lucide-minus。

<template>
  <UCheckbox default-value="indeterminate" indeterminate-icon="i-lucide-plus" />
</template>
您可以在ui.icons.minus键下的app.config.ts中全局自定义此图标。
你可以在你的ui.icons.minus下的ui.icons.minus键中全局自定义这个图标。

Label

使用label属性设置复选框的标签。

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

当使用required属性时，标签旁边会添加一个星号。

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

说明

使用description属性设置复选框的描述。

This is a checkbox.

<template>
  <UCheckbox label="Check me" description="This is a checkbox." />
</template>

Icon

使用icon属性将复选框的图标设置为i-lucide-check。

<template>
  <UCheckbox icon="i-lucide-heart" default-value label="Check me" />
</template>
你可以在你的app.config.ts中的ui.icons.check键下全局自定义这个图标。
您可以在ui.icons.check键下的vite.config.ts中全局自定义此图标。

Color

使用color属性更改复选框的颜色。

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

Variant

使用variant prop更改Checkbox的变体。

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

Size

使用size属性更改复选框的大小。

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

指示灯

使用indicator道具更改位置或隐藏指示器. start。

当indicator为hidden时，图标将显示在标签上方。
<template>
  <UCheckbox
    indicator="hidden"
    variant="card"
    icon="i-lucide-heart"
    default-value
    label="Check me"
  />
</template>

禁用

使用disabled prop禁用复选框。

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

API

Props

Prop Default Type
as
'div'
any

The element or component this component should render as.

label
string
description
string
color
'primary'
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
variant
'list'
"card" | "list"
size
'md'
"xs" | "sm" | "md" | "lg" | "xl"
indicator
'start'
"start" | "end" | "hidden"

Position of the indicator.

highlight
boolean

Highlight the ring color like a focus state.

icon
appConfig.ui.icons.check
any

The icon displayed when checked, or above the label when indicator is hidden.

indeterminateIcon
appConfig.ui.icons.minus
any

The icon displayed when the checkbox is indeterminate.

disabled
boolean

When true, prevents the user from interacting with the checkbox

required
boolean

When true, indicates that the user must set the value before the owning form can be submitted.

name
string

The name of the field. Submitted with its owning form as part of a name/value pair.

value
"on"
null | string | number | bigint | Record<string, any>

The value given as data when submitted with a name.

id
string

Id of the element

defaultValue
T | "indeterminate"

The value of the checkbox when it is initially rendered. Use when you do not need to control its value.

modelValue
null | T | "indeterminate"

The controlled value of the checkbox. Can be binded with v-model.

trueValue
T

The value used when the checkbox is checked. Defaults to true.

falseValue
T

The value used when the checkbox is unchecked. Defaults to false.

autofocus
false | true | "true" | "false"
ui
{ root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }
此组件还支持所有原生<button> HTML属性。

Slots

Slot Type
label
{ label: string | undefined; }
description
{ description: string | undefined; }

Emits

Event Type
change
[event: Event]
update:modelValue
[value: T | "indeterminate"]

Theme

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-accented overflow-hidden focus-visible:outline-none',
        indicator: 'flex items-center justify-center size-full text-inverted',
        icon: 'shrink-0',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            indicator: 'bg-primary'
          },
          secondary: {
            indicator: 'bg-secondary'
          },
          success: {
            indicator: 'bg-success'
          },
          info: {
            indicator: 'bg-info'
          },
          warning: {
            indicator: 'bg-warning'
          },
          error: {
            indicator: 'bg-error'
          },
          neutral: {
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: [
              'border border-default rounded-lg hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-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:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        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:not-has-focus-visible:not-has-data-[state=checked]: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: '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 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
          }
        },
        {
          color: 'primary',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible: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: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:bg-elevated'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: 'not-has-disabled:border-primary not-has-disabled:has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'neutral',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: 'not-has-disabled:border-inverted not-has-disabled:has-data-[state=checked]:border-inverted'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-inverted'
          }
        }
      ],
      defaultVariants: {
        highlight: false,
        size: 'md',
        color: 'primary',
        variant: 'list',
        indicator: 'start'
      }
    }
  }
})
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',
            container: 'flex items-center',
            base: 'rounded-sm ring ring-inset ring-accented overflow-hidden focus-visible:outline-none',
            indicator: 'flex items-center justify-center size-full text-inverted',
            icon: 'shrink-0',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                indicator: 'bg-primary'
              },
              secondary: {
                indicator: 'bg-secondary'
              },
              success: {
                indicator: 'bg-success'
              },
              info: {
                indicator: 'bg-info'
              },
              warning: {
                indicator: 'bg-warning'
              },
              error: {
                indicator: 'bg-error'
              },
              neutral: {
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                root: ''
              },
              card: {
                root: [
                  'border border-default rounded-lg hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-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:content-['*'] after:ms-0.5 after:text-error"
              }
            },
            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:not-has-focus-visible:not-has-data-[state=checked]: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: '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 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
              }
            },
            {
              color: 'primary',
              variant: 'list',
              indicator: 'hidden',
              class: {
                root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'list',
              indicator: 'hidden',
              class: {
                root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible: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: 'neutral',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:bg-elevated'
              }
            },
            {
              variant: 'card',
              disabled: true,
              class: {
                root: 'cursor-not-allowed'
              }
            },
            {
              color: 'primary',
              indicator: 'hidden',
              highlight: true,
              class: {
                root: 'not-has-disabled:border-primary not-has-disabled:has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              indicator: 'hidden',
              highlight: true,
              class: {
                root: 'not-has-disabled:border-inverted not-has-disabled:has-data-[state=checked]:border-inverted'
              }
            },
            {
              color: 'primary',
              highlight: true,
              class: {
                base: 'ring-primary'
              }
            },
            {
              color: 'neutral',
              highlight: true,
              class: {
                base: 'ring-inverted'
              }
            }
          ],
          defaultVariants: {
            highlight: false,
            size: 'md',
            color: 'primary',
            variant: 'list',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

Changelog

No recent changes

Skeleton

A placeholder to show while content is loading.

CheckboxGroup

A set of checkboxes to select multiple options from a list.