CheckboxGroup

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

用法

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

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

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

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

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

项目

使用items prop作为字符串或数字的数组：

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
const value = ref(['System'])
</script>

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

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

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

您也可以传递具有下列属性的物件数组：

  • label?: string
  • description?: string
  • value?: string
  • disabled?: boolean 058x-059x-056x-057x-058x-056x-057x-058x
  • class?: any
  • ui?: { item?: ClassNameValue, container?: ClassNameValue, base?: ClassNameValue, 'indicator'?: ClassNameValue, icon?: ClassNameValue, wrapper?: ClassNameValue, label?: ClassNameValue, description?: ClassNameValue }

Matches your device settings.

Always uses the light theme.

Always uses the dark theme.

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

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'Matches your device settings.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'Always uses the light theme.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'Always uses the dark theme.',
    value: 'dark'
  }
])
const value = ref([
  'system'
])
</script>

<template>
  <UCheckboxGroup v-model="value" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'Matches your device settings.',
    value: 'system'
  },
  {
    label: 'Light',
    description: 'Always uses the light theme.',
    value: 'light'
  },
  {
    label: 'Dark',
    description: 'Always uses the dark theme.',
    value: 'dark'
  }
])
const value = ref([
  'system'
])
</script>

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

值密钥

您可以通过使用value-key prop.xml将用于设置值的属性更改为value。

Matches your device settings.

Always uses the light theme.

Always uses the dark theme.

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

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'Matches your device settings.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'Always uses the light theme.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'Always uses the dark theme.',
    id: 'dark'
  }
])
const value = ref([
  'light'
])
</script>

<template>
  <UCheckboxGroup v-model="value" value-key="id" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    description: 'Matches your device settings.',
    id: 'system'
  },
  {
    label: 'Light',
    description: 'Always uses the light theme.',
    id: 'light'
  },
  {
    label: 'Dark',
    description: 'Always uses the dark theme.',
    id: 'dark'
  }
])
const value = ref([
  'light'
])
</script>

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

Legend

使用legend属性设置CheckboxGroup的图例。

Theme
<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup legend="Theme" :default-value="['System']" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'

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

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

Color

使用color属性更改CheckboxGroup的颜色。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup color="neutral" :default-value="['System']" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['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[]>([
  {
    label: 'System',
    value: 'system',
    description: 'Matches your device settings.'
  },
  {
    label: 'Light',
    value: 'light',
    description: 'Always uses the light theme.'
  },
  {
    label: 'Dark',
    value: 'dark',
    description: 'Always uses the dark theme.'
  }
])
</script>

<template>
  <UCheckboxGroup color="primary" variant="card" :default-value="['system']" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    value: 'system',
    description: 'Matches your device settings.'
  },
  {
    label: 'Light',
    value: 'light',
    description: 'Always uses the light theme.'
  },
  {
    label: 'Dark',
    value: 'dark',
    description: 'Always uses the dark theme.'
  }
])
</script>

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

Size

使用size属性更改CheckboxGroup的大小。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup size="xl" variant="list" :default-value="['System']" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'

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

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

方向

使用orientation属性将CheckboxGroup.xml的方向更改为vertical。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="['System']"
    :items="items"
  />
</template>
<script setup lang="ts">
import { ref } from 'vue'

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

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

指示器

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

当指示器可见时，项目的icon将替换复选标记，当项目的hidden时，项目的icon将显示在标签上方。
<script setup lang="ts">
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    icon: 'i-lucide-monitor',
    value: 'System',
    class: 'w-20'
  },
  {
    label: 'Light',
    icon: 'i-lucide-sun',
    class: 'w-20',
    value: 'Light'
  },
  {
    label: 'Dark',
    icon: 'i-lucide-moon',
    class: 'w-20',
    value: 'Dark'
  }
])
</script>

<template>
  <UCheckboxGroup
    indicator="hidden"
    orientation="horizontal"
    variant="table"
    :default-value="['System']"
    :items="items"
  />
</template>
<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nuxt/ui'

const items = ref<CheckboxGroupItem[]>([
  {
    label: 'System',
    icon: 'i-lucide-monitor',
    value: 'System',
    class: 'w-20'
  },
  {
    label: 'Light',
    icon: 'i-lucide-sun',
    class: 'w-20',
    value: 'Light'
  },
  {
    label: 'Dark',
    icon: 'i-lucide-moon',
    class: 'w-20',
    value: 'Dark'
  }
])
</script>

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

禁用

使用disabled属性禁用CheckboxGroup。

<script setup lang="ts">
const items = ref(['System', 'Light', 'Dark'])
</script>

<template>
  <UCheckboxGroup disabled :default-value="['System']" :items="items" />
</template>
<script setup lang="ts">
import { ref } from 'vue'

const items = ref(['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'
VK

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

labelKey
'label'
keyof Extract<NestedItem<T>, object> & string | DotPathKeys<Extract<NestedItem<T>, object>>

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

descriptionKey
'description'
keyof Extract<NestedItem<T>, object> & string | DotPathKeys<Extract<NestedItem<T>, object>>

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

items
T
modelValue
GetItemValue<T, VK, undefined, NestedItem<T>>[]

The controlled value of the CheckboxGroup. Can be bind as v-model.

defaultValue
GetItemValue<T, VK, undefined, NestedItem<T>>[]

The value of the CheckboxGroup when initially rendered. Use when you do not need to control the state of the CheckboxGroup.

size
'md'
"xs" | "sm" | "md" | "lg" | "xl"
variant
'list'
"table" | "list" | "card"
orientation
'vertical'
"horizontal" | "vertical"

The orientation the checkbox buttons are laid out.

disabled
boolean

When true, prevents the user from interacting with the checkboxes

loop
false
boolean

Whether keyboard navigation should loop around

name
string

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

required
boolean

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

icon
appConfig.ui.icons.check
any

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

color
'primary'
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
highlight
boolean

Highlight the ring color like a focus state.

indicator
'start'
"start" | "end" | "hidden"

Position of the indicator.

ui
{ root?: SlotClass; fieldset?: SlotClass; legend?: SlotClass; item?: SlotClass; } & { root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }

Slots

Slot Type
legend
{}
label
{ item: T[number] & { id: string; }; }
description
{ item: T[number] & { id: string; }; }

Emits

Event Type
update:modelValue
[value: GetItemValue<T, VK, undefined, NestedItem<T>>[]]
change
[event: Event]

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: {
            fieldset: 'flex-wrap'
          },
          card: {
            fieldset: 'flex-wrap'
          },
          table: {
            item: [
              'border border-default hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-elevated/50',
              'transition-colors'
            ]
          }
        },
        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"
          }
        },
        highlight: {
          true: {},
          false: {}
        },
        disabled: {
          true: {}
        }
      },
      compoundVariants: [
        {
          color: 'primary',
          variant: 'table',
          class: {
            item: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'table',
          class: {
            item: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
          }
        },
        {
          variant: 'table',
          highlight: false,
          class: {
            item: 'hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:border-accented'
          }
        },
        {
          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'
          }
        }
      ],
      defaultVariants: {
        highlight: false,
        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: {
                fieldset: 'flex-wrap'
              },
              card: {
                fieldset: 'flex-wrap'
              },
              table: {
                item: [
                  'border border-default hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-elevated/50',
                  'transition-colors'
                ]
              }
            },
            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"
              }
            },
            highlight: {
              true: {},
              false: {}
            },
            disabled: {
              true: {}
            }
          },
          compoundVariants: [
            {
              color: 'primary',
              variant: 'table',
              class: {
                item: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'table',
              class: {
                item: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
              }
            },
            {
              variant: 'table',
              highlight: false,
              class: {
                item: 'hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:border-accented'
              }
            },
            {
              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'
              }
            }
          ],
          defaultVariants: {
            highlight: false,
            size: 'md',
            variant: 'list',
            color: 'primary'
          }
        }
      }
    })
  ]
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

Changelog

No recent changes

Checkbox

An input element to toggle between checked and unchecked states.

ColorPicker

A component to select a color.