CheckboxGroup

CheckboxGroupサイトマップ
リストから複数のオプションを選択するチェックボックスのセット。

使用法

v-modelディレクティブを使用してCheckboxGroupの値を制御し、状態を制御する必要がない場合はdefault-valueプロパティを使用して初期値を設定します。

<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プロパティを文字列または数値の配列として使用します：

<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
  • icon?: string
  • 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キー

value-keyプロパティを使用して、値を設定するために使用するプロパティを変更できます。デフォルトは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プロパティを使用して、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

orientationプロパティを使用して、CheckboxGroupの向きを変更します。デフォルトは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の場合はラベルの上に表示されます。
<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; }

スロット

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.