Checkbox

チェックボックスサイトマップ
チェック状態とチェックされていない状態を切り替えるinput要素。

使用法

v-modelディレクティブを使用して、チェックボックスのチェック状態を制御します。

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

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

const value = ref(true)
</script>

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

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

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

不定元

v-modelディレクティブまたはdefault-valueプロパティのindeterminate値を使用して、チェックボックスをindeterminate stateに設定します。

<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

labelプロパティを使用して、チェックボックスのラベルを設定します。

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

requiredプロパティを使用する場合、ラベルの横にアスタリスクが追加されます。

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

Description

descriptionプロパティを使用して、チェックボックスの説明を設定します。

This is a checkbox.

<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

colorプロパティを使用して、チェックボックスの色を変更します。

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

Variant

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

indicatorプロパティを使用して位置を変更したり、インジケーターを非表示にしたりします。デフォルトはstartです。

indicatorがhiddenの場合、代わりにラベルの上にアイコンが表示されます。
<template>
  <UCheckbox
    indicator="hidden"
    variant="card"
    icon="i-lucide-heart"
    default-value
    label="Check me"
  />
</template>

無効

disabledプロパティを使用してチェックボックスを無効にします。

<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'
"primary" | "secondary" | "success" | "info" | "warning" | "error" | "neutral"
variant
'list'
"card" | "list"
size
'md'
"xs" | "sm" | "md" | "lg" | "xl"
indicator
'start'
"start" | "end" | "hidden"

Position of the indicator.

highlight
boolean

Highlight the ring color like a focus state.

icon
appConfig.ui.icons.check
any

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

indeterminateIcon
appConfig.ui.icons.minus
any

The icon displayed when the checkbox is indeterminate.

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

defaultValue
T | "indeterminate"

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

modelValue
null | T | "indeterminate"

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

trueValue
T

The value used when the checkbox is checked. Defaults to true.

falseValue
T

The value used when the checkbox is unchecked. Defaults to false.

autofocus
false | true | "true" | "false"
ui
{ root?: SlotClass; container?: SlotClass; base?: SlotClass; indicator?: SlotClass; icon?: SlotClass; wrapper?: SlotClass; label?: SlotClass; description?: SlotClass; }
このコンポーネントはすべてのネイティブ<button> HTML属性もサポートします。

スロット

Slot Type
label
{ label: string | undefined; }
description
{ description: string | undefined; }

Emits

Event Type
change
[event: Event]
update:modelValue
[value: T | "indeterminate"]

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-none',
        indicator: 'flex items-center justify-center size-full text-inverted',
        icon: 'shrink-0',
        wrapper: 'w-full',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            indicator: 'bg-primary'
          },
          secondary: {
            indicator: 'bg-secondary'
          },
          success: {
            indicator: 'bg-success'
          },
          info: {
            indicator: 'bg-info'
          },
          warning: {
            indicator: 'bg-warning'
          },
          error: {
            indicator: 'bg-error'
          },
          neutral: {
            indicator: 'bg-inverted'
          }
        },
        variant: {
          list: {
            root: ''
          },
          card: {
            root: [
              'border border-default rounded-lg hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-elevated/50',
              'transition-colors'
            ]
          }
        },
        indicator: {
          start: {
            root: 'flex-row',
            wrapper: 'ms-2'
          },
          end: {
            root: 'flex-row-reverse',
            wrapper: 'me-2'
          },
          hidden: {
            base: 'sr-only',
            wrapper: 'flex flex-col items-center gap-1 text-center'
          }
        },
        size: {
          xs: {
            base: 'size-3',
            icon: 'size-2.5',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'size-3.5',
            icon: 'size-3',
            container: 'h-4',
            wrapper: 'text-xs'
          },
          md: {
            base: 'size-4',
            icon: 'size-3.5',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'size-4.5',
            icon: 'size-4',
            container: 'h-5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'size-5',
            icon: 'size-4.5',
            container: 'h-6',
            wrapper: 'text-base'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-error"
          }
        },
        disabled: {
          true: {
            root: 'opacity-75',
            base: 'cursor-not-allowed',
            label: 'cursor-not-allowed',
            description: 'cursor-not-allowed'
          }
        },
        highlight: {
          true: '',
          false: ''
        },
        checked: {
          true: ''
        }
      },
      compoundVariants: [
        {
          indicator: 'hidden',
          class: {
            container: 'h-auto'
          }
        },
        {
          variant: 'card',
          highlight: false,
          class: {
            root: 'hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:border-accented'
          }
        },
        {
          size: 'xs',
          indicator: 'hidden',
          class: {
            icon: 'size-3'
          }
        },
        {
          size: 'sm',
          indicator: 'hidden',
          class: {
            icon: 'size-3.5'
          }
        },
        {
          size: 'md',
          indicator: 'hidden',
          class: {
            icon: 'size-4'
          }
        },
        {
          size: 'lg',
          indicator: 'hidden',
          class: {
            icon: 'size-4.5'
          }
        },
        {
          size: 'xl',
          indicator: 'hidden',
          class: {
            icon: 'size-5'
          }
        },
        {
          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: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-primary/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-primary'
          }
        },
        {
          color: 'neutral',
          variant: 'list',
          indicator: [
            'start',
            'end'
          ],
          class: {
            base: 'outline-inverted/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-inverted'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
          }
        },
        {
          color: 'primary',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
          }
        },
        {
          color: 'neutral',
          variant: 'list',
          indicator: 'hidden',
          class: {
            root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
          }
        },
        {
          color: 'primary',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-primary/50 has-data-[state=checked]:bg-primary/10'
          }
        },
        {
          color: 'neutral',
          variant: 'card',
          class: {
            root: 'has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:bg-elevated'
          }
        },
        {
          variant: 'card',
          disabled: true,
          class: {
            root: 'cursor-not-allowed'
          }
        },
        {
          color: 'primary',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: 'not-has-disabled:border-primary not-has-disabled:has-data-[state=checked]:border-primary'
          }
        },
        {
          color: 'neutral',
          indicator: 'hidden',
          highlight: true,
          class: {
            root: 'not-has-disabled:border-inverted not-has-disabled:has-data-[state=checked]:border-inverted'
          }
        },
        {
          color: 'primary',
          highlight: true,
          class: {
            base: 'ring-primary'
          }
        },
        {
          color: 'neutral',
          highlight: true,
          class: {
            base: 'ring-inverted'
          }
        }
      ],
      defaultVariants: {
        highlight: false,
        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-none',
            indicator: 'flex items-center justify-center size-full text-inverted',
            icon: 'shrink-0',
            wrapper: 'w-full',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                indicator: 'bg-primary'
              },
              secondary: {
                indicator: 'bg-secondary'
              },
              success: {
                indicator: 'bg-success'
              },
              info: {
                indicator: 'bg-info'
              },
              warning: {
                indicator: 'bg-warning'
              },
              error: {
                indicator: 'bg-error'
              },
              neutral: {
                indicator: 'bg-inverted'
              }
            },
            variant: {
              list: {
                root: ''
              },
              card: {
                root: [
                  'border border-default rounded-lg hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:bg-elevated/50',
                  'transition-colors'
                ]
              }
            },
            indicator: {
              start: {
                root: 'flex-row',
                wrapper: 'ms-2'
              },
              end: {
                root: 'flex-row-reverse',
                wrapper: 'me-2'
              },
              hidden: {
                base: 'sr-only',
                wrapper: 'flex flex-col items-center gap-1 text-center'
              }
            },
            size: {
              xs: {
                base: 'size-3',
                icon: 'size-2.5',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              sm: {
                base: 'size-3.5',
                icon: 'size-3',
                container: 'h-4',
                wrapper: 'text-xs'
              },
              md: {
                base: 'size-4',
                icon: 'size-3.5',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              lg: {
                base: 'size-4.5',
                icon: 'size-4',
                container: 'h-5',
                wrapper: 'text-sm'
              },
              xl: {
                base: 'size-5',
                icon: 'size-4.5',
                container: 'h-6',
                wrapper: 'text-base'
              }
            },
            required: {
              true: {
                label: "after:content-['*'] after:ms-0.5 after:text-error"
              }
            },
            disabled: {
              true: {
                root: 'opacity-75',
                base: 'cursor-not-allowed',
                label: 'cursor-not-allowed',
                description: 'cursor-not-allowed'
              }
            },
            highlight: {
              true: '',
              false: ''
            },
            checked: {
              true: ''
            }
          },
          compoundVariants: [
            {
              indicator: 'hidden',
              class: {
                container: 'h-auto'
              }
            },
            {
              variant: 'card',
              highlight: false,
              class: {
                root: 'hover:not-has-disabled:not-has-focus-visible:not-has-data-[state=checked]:border-accented'
              }
            },
            {
              size: 'xs',
              indicator: 'hidden',
              class: {
                icon: 'size-3'
              }
            },
            {
              size: 'sm',
              indicator: 'hidden',
              class: {
                icon: 'size-3.5'
              }
            },
            {
              size: 'md',
              indicator: 'hidden',
              class: {
                icon: 'size-4'
              }
            },
            {
              size: 'lg',
              indicator: 'hidden',
              class: {
                icon: 'size-4.5'
              }
            },
            {
              size: 'xl',
              indicator: 'hidden',
              class: {
                icon: 'size-5'
              }
            },
            {
              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: 'list',
              indicator: [
                'start',
                'end'
              ],
              class: {
                base: 'outline-primary/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-primary'
              }
            },
            {
              color: 'neutral',
              variant: 'list',
              indicator: [
                'start',
                'end'
              ],
              class: {
                base: 'outline-inverted/25 focus-visible:outline-solid focus-visible:outline-3 focus-visible:ring-inverted'
              }
            },
            {
              color: 'primary',
              variant: 'card',
              class: {
                root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
              }
            },
            {
              color: 'primary',
              variant: 'list',
              indicator: 'hidden',
              class: {
                root: 'outline-primary/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-primary has-focus-visible:z-[1]'
              }
            },
            {
              color: 'neutral',
              variant: 'list',
              indicator: 'hidden',
              class: {
                root: 'outline-inverted/25 has-focus-visible:outline-3 not-has-disabled:has-focus-visible:border-inverted has-focus-visible:z-[1]'
              }
            },
            {
              color: 'primary',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-primary/50 has-data-[state=checked]:bg-primary/10'
              }
            },
            {
              color: 'neutral',
              variant: 'card',
              class: {
                root: 'has-data-[state=checked]:border-inverted/50 has-data-[state=checked]:bg-elevated'
              }
            },
            {
              variant: 'card',
              disabled: true,
              class: {
                root: 'cursor-not-allowed'
              }
            },
            {
              color: 'primary',
              indicator: 'hidden',
              highlight: true,
              class: {
                root: 'not-has-disabled:border-primary not-has-disabled:has-data-[state=checked]:border-primary'
              }
            },
            {
              color: 'neutral',
              indicator: 'hidden',
              highlight: true,
              class: {
                root: 'not-has-disabled:border-inverted not-has-disabled:has-data-[state=checked]:border-inverted'
              }
            },
            {
              color: 'primary',
              highlight: true,
              class: {
                base: 'ring-primary'
              }
            },
            {
              color: 'neutral',
              highlight: true,
              class: {
                base: 'ring-inverted'
              }
            }
          ],
          defaultVariants: {
            highlight: false,
            size: 'md',
            color: 'primary',
            variant: 'list',
            indicator: 'start'
          }
        }
      }
    })
  ]
})
Some colors in compoundVariants are omitted for readability. Check out the source code on GitHub.

Changelog

No recent changes

Skeleton

A placeholder to show while content is loading.

CheckboxGroup

A set of checkboxes to select multiple options from a list.