Lzh on GitHub

CheckboxGroup

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

用法

使用 v-model 指令来控制 CheckboxGroup 的值，或者使用 default-value prop 来设置初始值，当你不需要控制其状态时。

Items

使用 items prop，它是一个字符串或数字数组：

<script setup lang="ts">
import type { CheckboxGroupItem, CheckboxGroupValue } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
const value = ref<CheckboxGroupValue[]>(['System'])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>

你也可以传递一个包含以下属性的对象数组：

  • label?: string
  • description?: string
  • value?: string
  • disabled?: boolean
  • class?: any
  • ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, icon?: ClassNameValue, wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }

This is the first option.

This is the second option.

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem, CheckboxGroupValue } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    value: 'dark'
  }
])
const value = ref<CheckboxGroupValue[]>([
  'system'
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
当使用对象时，你需要引用 v-model 指令或 default-value prop 中对象的 value 属性。

Value Key

你可以使用 value-key prop 来更改用于设置值的属性。默认为 value。

This is the first option.

This is the second option.

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem, CheckboxGroupValue } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'This is the first option.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'This is the second option.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'This is the third option.',
    id: 'dark'
  }
])
const value = ref<CheckboxGroupValue[]>([
  'light'
])
</script>

<template>
  <UCheckboxGroup v-model="value" value-key="id" :items="items" />
</template>

图例 (Legend)

使用 legend prop 来设置 CheckboxGroup 的图例。

Theme
<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup legend="Theme" :default-value="['System']" :items="items" />
</template>

颜色 (Color)

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

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup color="neutral" :default-value="['System']" :items="items" />
</template>

变体 (Variant)

使用 variant prop 来改变 CheckboxGroup 的变体（样式）。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup color="primary" variant="card" :default-value="['System']" :items="items" />
</template>

尺寸 (Size)

使用 size prop 来改变 CheckboxGroup 的尺寸。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup size="xl" variant="list" :default-value="['System']" :items="items" />
</template>

方向 (Orientation)

使用 orientation prop 来改变 CheckboxGroup 的方向。默认为 vertical（垂直）。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="['System']"
    :items="items"
  />
</template>

指示器 (Indicator)

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

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup indicator="end" variant="card" :default-value="['System']" :items="items" />
</template>

禁用 (Disabled)

使用 disabled prop 来禁用 CheckboxGroup。

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup disabled :default-value="['System']" :items="items" />
</template>

API

Props

Prop Default Type
as

'div'

any

The element or component this component should render as.

legend

string

valueKey

'value'

string

When items is an array of objects, select the field to use as the value.

labelKey

'label'

string

When items is an array of objects, select the field to use as the label.

descriptionKey

'description'

string

When items is an array of objects, select the field to use as the description.

items

CheckboxGroupItem[]

size

'md'

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

variant

'list'

"table" | "list" | "card"

orientation

'vertical'

"horizontal" | "vertical"

The orientation the checkbox buttons are laid out.

defaultValue

AcceptableValue[]

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

modelValue

AcceptableValue[]

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

disabled

boolean

When true, prevents the user from interacting with the checkboxes

loop

false

boolean

Whether keyboard navigation should loop around

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.

icon

appConfig.ui.icons.check

string

The icon displayed when checked.

color

'primary'

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

indicator

'start'

"start" | "end" | "hidden"

Position of the indicator.

ui

{ root?: ClassNameValue; fieldset?: ClassNameValue; legend?: ClassNameValue; item?: ClassNameValue; } & { root?: ClassNameValue; ... 6 more ...; description?: ClassNameValue; }

Slots

Slot Type
legend

{}

label

{ item: CheckboxGroupItem & { id: string; }; }

description

{ item: CheckboxGroupItem & { id: string; }; }

Emits

Event Type
change

Event

update:modelValue

AcceptableValue[]

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    checkboxGroup: {
      slots: {
        root: 'relative',
        fieldset: 'flex gap-x-2',
        legend: 'mb-1 block font-medium text-default',
        item: ''
      },
      variants: {
        orientation: {
          horizontal: {
            fieldset: 'flex-row'
          },
          vertical: {
            fieldset: 'flex-col'
          }
        },
        color: {
          primary: {},
          secondary: {},
          success: {},
          info: {},
          warning: {},
          error: {},
          neutral: {}
        },
        variant: {
          list: {},
          card: {},
          table: {
            item: 'border border-muted'
          }
        },
        size: {
          xs: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          sm: {
            fieldset: 'gap-y-0.5',
            legend: 'text-xs'
          },
          md: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          lg: {
            fieldset: 'gap-y-1',
            legend: 'text-sm'
          },
          xl: {
            fieldset: 'gap-y-1.5',
            legend: 'text-base'
          }
        },
        required: {
          true: {
            legend: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        }
      },
      compoundVariants: [
        {
          size: 'xs',
          variant: 'table',
          class: {
            item: 'p-2.5'
          }
        },
        {
          size: 'sm',
          variant: 'table',
          class: {
            item: 'p-3'
          }
        },
        {
          size: 'md',
          variant: 'table',
          class: {
            item: 'p-3.5'
          }
        },
        {
          size: 'lg',
          variant: 'table',
          class: {
            item: 'p-4'
          }
        },
        {
          size: 'xl',
          variant: 'table',
          class: {
            item: 'p-4.5'
          }
        },
        {
          orientation: 'horizontal',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
            fieldset: 'gap-0 -space-x-px'
          }
        },
        {
          orientation: 'vertical',
          variant: 'table',
          class: {
            item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
            fieldset: 'gap-0 -space-y-px'
          }
        },
        {
          color: 'primary',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'table',
          class: {
            item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
          }
        },
        {
          variant: 'table',
          disabled: true,
          class: {
            item: 'cursor-not-allowed opacity-75'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        variant: 'list',
        color: 'primary'
      }
    }
  }
})
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: {
        checkboxGroup: {
          slots: {
            root: 'relative',
            fieldset: 'flex gap-x-2',
            legend: 'mb-1 block font-medium text-default',
            item: ''
          },
          variants: {
            orientation: {
              horizontal: {
                fieldset: 'flex-row'
              },
              vertical: {
                fieldset: 'flex-col'
              }
            },
            color: {
              primary: {},
              secondary: {},
              success: {},
              info: {},
              warning: {},
              error: {},
              neutral: {}
            },
            variant: {
              list: {},
              card: {},
              table: {
                item: 'border border-muted'
              }
            },
            size: {
              xs: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              sm: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              md: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              lg: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              xl: {
                fieldset: 'gap-y-1.5',
                legend: 'text-base'
              }
            },
            required: {
              true: {
                legend: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: 'table',
              class: {
                item: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: 'table',
              class: {
                item: 'p-3'
              }
            },
            {
              size: 'md',
              variant: 'table',
              class: {
                item: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: 'table',
              class: {
                item: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: 'table',
              class: {
                item: 'p-4.5'
              }
            },
            {
              orientation: 'horizontal',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
                fieldset: 'gap-0 -space-x-px'
              }
            },
            {
              orientation: 'vertical',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
                fieldset: 'gap-0 -space-y-px'
              }
            },
            {
              color: 'primary',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              variant: 'table',
              disabled: true,
              class: {
                item: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            variant: 'list',
            color: 'primary'
          }
        }
      }
    })
  ]
})
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: {
        checkboxGroup: {
          slots: {
            root: 'relative',
            fieldset: 'flex gap-x-2',
            legend: 'mb-1 block font-medium text-default',
            item: ''
          },
          variants: {
            orientation: {
              horizontal: {
                fieldset: 'flex-row'
              },
              vertical: {
                fieldset: 'flex-col'
              }
            },
            color: {
              primary: {},
              secondary: {},
              success: {},
              info: {},
              warning: {},
              error: {},
              neutral: {}
            },
            variant: {
              list: {},
              card: {},
              table: {
                item: 'border border-muted'
              }
            },
            size: {
              xs: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              sm: {
                fieldset: 'gap-y-0.5',
                legend: 'text-xs'
              },
              md: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              lg: {
                fieldset: 'gap-y-1',
                legend: 'text-sm'
              },
              xl: {
                fieldset: 'gap-y-1.5',
                legend: 'text-base'
              }
            },
            required: {
              true: {
                legend: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            }
          },
          compoundVariants: [
            {
              size: 'xs',
              variant: 'table',
              class: {
                item: 'p-2.5'
              }
            },
            {
              size: 'sm',
              variant: 'table',
              class: {
                item: 'p-3'
              }
            },
            {
              size: 'md',
              variant: 'table',
              class: {
                item: 'p-3.5'
              }
            },
            {
              size: 'lg',
              variant: 'table',
              class: {
                item: 'p-4'
              }
            },
            {
              size: 'xl',
              variant: 'table',
              class: {
                item: 'p-4.5'
              }
            },
            {
              orientation: 'horizontal',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-s-lg last-of-type:rounded-e-lg',
                fieldset: 'gap-0 -space-x-px'
              }
            },
            {
              orientation: 'vertical',
              variant: 'table',
              class: {
                item: 'first-of-type:rounded-t-lg last-of-type:rounded-b-lg',
                fieldset: 'gap-0 -space-y-px'
              }
            },
            {
              color: 'primary',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-primary/10 has-data-[state=checked]:border-primary/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'table',
              class: {
                item: 'has-data-[state=checked]:bg-elevated has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:z-[1]'
              }
            },
            {
              variant: 'table',
              disabled: true,
              class: {
                item: 'cursor-not-allowed opacity-75'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            variant: 'list',
            color: 'primary'
          }
        }
      }
    })
  ]
})
为了可读性，compoundVariants 中的某些颜色被省略。请查看 GitHub 上的源代码。

Checkbox

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

Chip

表示数值或状态的指示器。