Usage
The CheckboxGroup component allows users to select multiple values from a set of options.
<template>
<UCheckboxGroup
v-model="selected"
legend="Select your interests"
:items="items"
/>
</template>
<script setup>
const selected = ref([])
const items = [
{ value: 'design', label: 'Design' },
{ value: 'development', label: 'Development' },
{ value: 'marketing', label: 'Marketing' }
]
</script>
With Descriptions
Add descriptions to provide more context for each option:
<template>
<UCheckboxGroup
v-model="selected"
legend="Choose features"
:items="items"
/>
</template>
<script setup>
const selected = ref([])
const items = [
{
value: 'notifications',
label: 'Email Notifications',
description: 'Receive email updates about your account'
},
{
value: 'newsletter',
label: 'Newsletter',
description: 'Weekly digest of new features and updates'
},
{
value: 'marketing',
label: 'Marketing Emails',
description: 'Promotional content and special offers'
}
]
</script>
Simple Values
You can also use simple string or number values:
<template>
<UCheckboxGroup
v-model="selected"
legend="Select options"
:items="['Option 1', 'Option 2', 'Option 3']"
/>
</template>
<script setup>
const selected = ref([])
</script>
Horizontal Layout
<template>
<UCheckboxGroup
v-model="selected"
legend="Select options"
:items="items"
orientation="horizontal"
/>
</template>
<script setup>
const selected = ref([])
const items = ['Option 1', 'Option 2', 'Option 3']
</script>
Sizes
<template>
<div class="space-y-8">
<UCheckboxGroup
v-model="selected"
legend="Small"
:items="items"
size="sm"
/>
<UCheckboxGroup
v-model="selected"
legend="Medium"
:items="items"
size="md"
/>
<UCheckboxGroup
v-model="selected"
legend="Large"
:items="items"
size="lg"
/>
</div>
</template>
<script setup>
const selected = ref([])
const items = ['Option 1', 'Option 2', 'Option 3']
</script>
Colors
<template>
<UCheckboxGroup
v-model="selected"
legend="Select options"
:items="items"
color="success"
/>
</template>
<script setup>
const selected = ref([])
const items = ['Option 1', 'Option 2', 'Option 3']
</script>
Variants
<template>
<div class="space-y-8">
<UCheckboxGroup
v-model="selected"
legend="List variant"
:items="items"
variant="list"
/>
<UCheckboxGroup
v-model="selected"
legend="Default variant"
:items="items"
/>
</div>
</template>
<script setup>
const selected = ref([])
const items = ['Option 1', 'Option 2', 'Option 3']
</script>
Disabled Items
<template>
<UCheckboxGroup
v-model="selected"
legend="Select options"
:items="items"
/>
</template>
<script setup>
const selected = ref([])
const items = [
{ value: '1', label: 'Option 1' },
{ value: '2', label: 'Option 2 (disabled)', disabled: true },
{ value: '3', label: 'Option 3' }
]
</script>
Custom Keys
Use custom keys for value, label, and description fields:
<template>
<UCheckboxGroup
v-model="selected"
legend="Select options"
:items="items"
value-key="id"
label-key="name"
description-key="info"
/>
</template>
<script setup>
const selected = ref([])
const items = [
{ id: '1', name: 'Option 1', info: 'First option' },
{ id: '2', name: 'Option 2', info: 'Second option' },
{ id: '3', name: 'Option 3', info: 'Third option' }
]
</script>
Slots
<template>
<UCheckboxGroup v-model="selected" :items="items">
<template #legend>
<span class="font-bold">Custom Legend</span>
</template>
<template #label="{ item }">
<span class="uppercase">{{ item.label }}</span>
</template>
<template #description="{ item }">
<em>{{ item.description }}</em>
</template>
</UCheckboxGroup>
</template>
<script setup>
const selected = ref([])
const items = [
{ value: '1', label: 'Option 1', description: 'Description 1' },
{ value: '2', label: 'Option 2', description: 'Description 2' }
]
</script>
Props
The controlled value of the checkbox group. Can be bound with v-model.
The value of the checkbox group when initially rendered.
Array of items to render as checkboxes. Can be strings, numbers, or objects.
The legend text for the checkbox group fieldset.
When items is an array of objects, select the field to use as the value.
When items is an array of objects, select the field to use as the label.
descriptionKey
string
default:"description"
When items is an array of objects, select the field to use as the description.
The size of the checkboxes. Options: sm, md, lg.
The visual variant of the checkboxes.
The color theme of the checkboxes.
The orientation the checkboxes are laid out. Options: vertical, horizontal.
Position of the checkbox indicator. Options: start, end.
The icon displayed when checked.
When true, prevents user interaction with all checkboxes.
When true, indicates that at least one checkbox must be checked.
The name of the checkbox group for form submission.
When true, keyboard navigation will loop from last to first item.
The element or component this component should render as.
Additional CSS classes to apply to the root element.
UI customization object for styling different parts of the checkbox group.
Events
Emitted when any checkbox in the group changes.
Emitted when the selected values change.
Slots
Customize the legend content.
Customize the label content for each checkbox.
Customize the description content for each checkbox.