Lzh on GitHub

Checkbox

CheckboxGitHub
一个用于在选中和未选中状态之间切换的输入元素。

用法

使用 v-model 指令来控制 Checkbox 的选中状态。

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

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

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

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

不确定状态 (Indeterminate)

在 v-model 指令或 default-value prop 中使用 indeterminate 值，将 Checkbox 设置为 不确定状态。

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

不确定状态图标 (Indeterminate Icon)

使用 indeterminate-icon prop 来自定义不确定状态图标。默认为 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 prop 来设置 Checkbox 的标签。

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

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

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

描述

使用 description prop 来设置 Checkbox 的描述。

This is a checkbox.

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

图标 (Icon)

使用 icon prop 来设置 Checkbox 被选中时的图标。默认为 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)

使用 color prop 来改变 Checkbox 的颜色。

<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 prop 来改变 Checkbox 的尺寸。

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

指示器

使用 indicator prop 来改变指示器的位置或隐藏指示器。默认为 start。

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

禁用 (Disabled)

使用 disabled prop 来禁用 Checkbox。

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

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

variant

'list'

"list" | "card"

size

'md'

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

indicator

'start'

"start" | "end" | "hidden"

Position of the indicator.

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

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

modelValue

boolean | "indeterminate"

ui

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

Slots

Slot Type
label

{ label?: string | undefined; }

description

{ description?: string | undefined; }

Emits

Event Type
update:modelValue

[value: boolean | "indeterminate"]

change

[payload: Event]

可以通过 payload.target.value 访问 Checkbox 的值。

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

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