CheckboxGroup

Um conjunto de botões de checklist para selecionar várias opções em uma lista.

Uso

Use a diretiva v-model para controlar o valor do CheckboxGroup ou a prop default-value para definir o valor inicial quando você não precisa controlar o estado.

System

Light

Dark

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

<template>
  <NCheckboxGroup 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>
  <NCheckboxGroup v-model="value" :items="items" />
</template>

Itens

Use a prop items como um array de strings ou números:

System

Light

Dark

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

<template>
  <NCheckboxGroup 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>
  <NCheckboxGroup v-model="value" :items="items" />
</template>

Você também pode passar um array de objetos com as seguintes propriedades:

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 }

System

This is the first option.

Light

This is the second option.

Dark

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nitro/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([
  'system'
])
</script>

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

<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nitro/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([
  'system'
])
</script>

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

Ao usar objetos, você precisa referenciar a propriedade value do objeto na diretiva v-model ou na prop default-value.

Chave de valor

Você pode alterar a propriedade usada para definir o valor usando a prop value-key. O padrão é value.

System

This is the first option.

Light

This is the second option.

Dark

This is the third option.

<script setup lang="ts">
import type { CheckboxGroupItem } from '@nitro/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([
  'light'
])
</script>

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

<script setup lang="ts">
import { ref } from 'vue'
import type { CheckboxGroupItem } from '@nitro/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([
  'light'
])
</script>

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

Legenda

Use a prop legend para definir a legenda do CheckboxGroup.

legend

Theme

System

Light

Dark

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

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

<script setup lang="ts">
import { ref } from 'vue'

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

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

Cor

Use a prop color para alterar a cor do CheckboxGroup.

color

System

Light

Dark

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

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

<script setup lang="ts">
import { ref } from 'vue'

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

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

Variante

Use a prop variant para alterar a variante do CheckboxGroup.

color

variant

System

Light

Dark

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

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

<script setup lang="ts">
import { ref } from 'vue'

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

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

Tamanho

Use a prop size para alterar o tamanho do CheckboxGroup.

size

variant

System

Light

Dark

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

<template>
  <NCheckboxGroup 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>
  <NCheckboxGroup size="xl" variant="list" :default-value="['System']" :items="items" />
</template>

Orientação

Use a prop orientation para alterar a orientação do CheckboxGroup. O padrão é vertical.

orientation

variant

System

Light

Dark

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

<template>
  <NCheckboxGroup
    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>
  <NCheckboxGroup
    orientation="horizontal"
    variant="list"
    :default-value="['System']"
    :items="items"
  />
</template>

Indicador

Use a prop indicator para alterar a posição ou ocultar o indicador. O padrão é start.

indicator

variant

System

Light

Dark

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

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

<script setup lang="ts">
import { ref } from 'vue'

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

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

Desabilitado

Use a prop disabled para desabilitar o CheckboxGroup.

disabled

System

Light

Dark

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

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

<script setup lang="ts">
import { ref } from 'vue'

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

<template>
  <NCheckboxGroup 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.
`color`	`'primary'`	`"primary" \| "secondary" \| "accent" \| "success" \| "info" \| "warning" \| "error" \| "neutral"`
`highlight`		`boolean` Highlight the ring color like a focus state.
`indicator`	`'start'`	`"start" \| "end" \| "hidden"` Position of the indicator.
`icon`	`appConfig.ui.icons.check`	`any` The icon displayed when checked.
`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]`

Tema

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: {},
          accent: {},
          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"
          }
        },
        disabled: {
          true: {}
        }
      },
      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'
          }
        }
      ],
      defaultVariants: {
        size: 'md',
        variant: 'list',
        color: 'primary'
      }
    }
  }
})

vite.config.ts

import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nitro/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: {},
              accent: {},
              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"
              }
            },
            disabled: {
              true: {}
            }
          },
          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'
              }
            }
          ],
          defaultVariants: {
            size: 'md',
            variant: 'list',
            color: 'primary'
          }
        }
      }
    })
  ]
})

Some colors in compoundVariants are omitted for readability. Check out the source code on GitLab.

Changelog

No recent changes

Checkbox

Um elemento de input para alternar entre os estados marcado e desmarcado.

ColorPicker

Um componente para selecionar uma cor.