复选框

复选框GitHub
一个输入元素，用于在选中和未选中状态之间切换。

用法

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

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

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

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

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

不确定状态

在 v-model 指令或 default-value 属性中使用 indeterminate 值，将复选框设置为不确定状态.

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

不确定状态图标

使用 indeterminate-icon 属性自定义不确定状态图标。默认为 i-lucide-minus。

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

标签

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

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

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

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

描述

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

<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 键下全局自定义此图标。
您可以在 vite.config.ts 文件的 ui.icons.check 键下全局自定义此图标。

颜色

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

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

变体 新增

使用 variant 属性更改复选框的变体。

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

尺寸

使用 size 属性更改复选框的尺寸。

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

指示器 新增

使用 indicator 属性更改指示器的位置或隐藏指示器。默认为 start。

<template>
  <UCheckbox indicator="end" variant="card" default-value label="Check me" />
</template>

禁用

使用 disabled 属性禁用复选框。

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

API

属性

属性默认值类型
as

'div'

any

此组件应渲染成的元素或组件。

label

string

description

string

color

'primary'

"error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"

variant

'list'

"card" | "list"

size

'md'

"xs" | "sm" | "md" | "lg" | "xl"

indicator

'start'

"start" | "end" | "hidden"

指示器的位置。

icon

appConfig.ui.icons.check

string

选中时显示的图标。

indeterminateIcon

appConfig.ui.icons.minus

string

复选框处于不确定状态时显示的图标。

disabled

boolean

当为 true 时，阻止用户与复选框交互

value

"on"

null | string | number | Record<string, any>

当与 name 一起提交时作为数据提供的值。

name

string

字段的名称。作为名称/值对的一部分随所属表单一起提交。

required

boolean

当为 true 时，表示用户必须在提交所属表单之前设置值。

id

string

元素的 ID

defaultValue

boolean | "indeterminate"

复选框初次渲染时的值。当您不需要控制其值时使用。

modelValue

undefined

boolean | "indeterminate"

ui

{ root?: ClassNameValue; container?: ClassNameValue; base?: ClassNameValue; indicator?: ClassNameValue; icon?: ClassNameValue; wrapper?: ClassNameValue; label?: ClassNameValue; description?: ClassNameValue; }

插槽

插槽类型
label

{ label?: string | undefined; }

description

{ description?: string | undefined; }

事件

事件类型
change

[payload: Event]

update:modelValue

[value: boolean | "indeterminate"]

主题

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-2 focus-visible:outline-offset-2',
        indicator: 'flex items-center justify-center size-full text-inverted',
        icon: 'shrink-0 size-full',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'focus-visible:outline-primary',
            indicator: 'bg-primary'
          },
          secondary: {
            base: 'focus-visible:outline-secondary',
            indicator: 'bg-secondary'
          },
          success: {
            base: 'focus-visible:outline-success',
            indicator: 'bg-success'
          },
          info: {
            base: 'focus-visible:outline-info',
            indicator: 'bg-info'
          },
          warning: {
            base: 'focus-visible:outline-warning',
            indicator: 'bg-warning'
          },
          error: {
            base: 'focus-visible:outline-error',
            indicator: 'bg-error'
          },
          neutral: {
            base: 'focus-visible:outline-inverted',
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: 'border border-muted rounded-lg'
          }
        },
        indicator: {
          start: {
            root: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            root: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'text-center'
          }
        },
        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"
          }
        },
        disabled: {
          true: {
            base: 'cursor-not-allowed opacity-75',
            label: 'cursor-not-allowed opacity-75',
            description: 'cursor-not-allowed opacity-75'
          }
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          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: 'card',
          class: {
            root: 'has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-inverted'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed opacity-75'
          }
        }
      ],
      defaultVariants: {
        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-2 focus-visible:outline-offset-2',
            indicator: 'flex items-center justify-center size-full text-inverted',
            icon: 'shrink-0 size-full',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'focus-visible:outline-primary',
                indicator: 'bg-primary'
              },
              secondary: {
                base: 'focus-visible:outline-secondary',
                indicator: 'bg-secondary'
              },
              success: {
                base: 'focus-visible:outline-success',
                indicator: 'bg-success'
              },
              info: {
                base: 'focus-visible:outline-info',
                indicator: 'bg-info'
              },
              warning: {
                base: 'focus-visible:outline-warning',
                indicator: 'bg-warning'
              },
              error: {
                base: 'focus-visible:outline-error',
                indicator: 'bg-error'
              },
              neutral: {
                base: 'focus-visible:outline-inverted',
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                root: ''
              },
              card: {
                root: 'border border-muted rounded-lg'
              }
            },
            indicator: {
              start: {
                root: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                root: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'text-center'
              }
            },
            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"
              }
            },
            disabled: {
              true: {
                base: 'cursor-not-allowed opacity-75',
                label: 'cursor-not-allowed opacity-75',
                description: 'cursor-not-allowed opacity-75'
              }
            },
            checked: {
              true: ''
            }
          },
          compoundVariants: [
            {
              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: 'card',
              class: {
                root: 'has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-inverted'
              }
            },
            {
              variant: 'card',
              disabled: true,
              class: {
                root: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary',
            variant: 'list',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import uiPro from '@nuxt/ui-pro/vite'

export default defineConfig({
  plugins: [
    vue(),
    uiPro({
      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-2 focus-visible:outline-offset-2',
            indicator: 'flex items-center justify-center size-full text-inverted',
            icon: 'shrink-0 size-full',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'focus-visible:outline-primary',
                indicator: 'bg-primary'
              },
              secondary: {
                base: 'focus-visible:outline-secondary',
                indicator: 'bg-secondary'
              },
              success: {
                base: 'focus-visible:outline-success',
                indicator: 'bg-success'
              },
              info: {
                base: 'focus-visible:outline-info',
                indicator: 'bg-info'
              },
              warning: {
                base: 'focus-visible:outline-warning',
                indicator: 'bg-warning'
              },
              error: {
                base: 'focus-visible:outline-error',
                indicator: 'bg-error'
              },
              neutral: {
                base: 'focus-visible:outline-inverted',
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                root: ''
              },
              card: {
                root: 'border border-muted rounded-lg'
              }
            },
            indicator: {
              start: {
                root: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                root: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'text-center'
              }
            },
            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"
              }
            },
            disabled: {
              true: {
                base: 'cursor-not-allowed opacity-75',
                label: 'cursor-not-allowed opacity-75',
                description: 'cursor-not-allowed opacity-75'
              }
            },
            checked: {
              true: ''
            }
          },
          compoundVariants: [
            {
              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: 'card',
              class: {
                root: 'has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-inverted'
              }
            },
            {
              variant: 'card',
              disabled: true,
              class: {
                root: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            color: 'primary',
            variant: 'list',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
为了便于阅读，省略了 compoundVariants 中的部分颜色。请查看 GitHub 上的源代码。

Carousel

一个使用 Embla 构建的带有运动和滑动功能的轮播组件。

CheckboxGroup

一组复选按钮，用于从列表中选择多个选项。