Usage
The Checkbox component allows users to select or deselect options. It supports labels, descriptions, and indeterminate state.
<template>
<UCheckbox v-model="checked" label="Accept terms and conditions" />
</template>
<script setup>
const checked = ref(false)
</script>
With Description
Add a description to provide additional context:
<template>
<UCheckbox
v-model="checked"
label="Subscribe to newsletter"
description="Receive updates about new features and releases"
/>
</template>
<script setup>
const checked = ref(false)
</script>
Indeterminate State
The checkbox supports an indeterminate state for partial selections:
<template>
<UCheckbox
v-model="state"
label="Select all items"
/>
</template>
<script setup>
const state = ref('indeterminate')
</script>
Variants
Checkboxes come in different variants:
<template>
<div class="space-y-4">
<UCheckbox v-model="checked" label="List variant" variant="list" />
<UCheckbox v-model="checked" label="Default variant" />
</div>
</template>
<script setup>
const checked = ref(false)
</script>
Sizes
<template>
<div class="space-y-4">
<UCheckbox v-model="checked" label="Small" size="sm" />
<UCheckbox v-model="checked" label="Medium" size="md" />
<UCheckbox v-model="checked" label="Large" size="lg" />
</div>
</template>
<script setup>
const checked = ref(false)
</script>
Colors
<template>
<div class="space-y-4">
<UCheckbox v-model="checked" label="Primary" color="primary" />
<UCheckbox v-model="checked" label="Success" color="success" />
<UCheckbox v-model="checked" label="Warning" color="warning" />
<UCheckbox v-model="checked" label="Error" color="error" />
</div>
</template>
<script setup>
const checked = ref(false)
</script>
Disabled
<template>
<UCheckbox v-model="checked" label="Disabled checkbox" disabled />
</template>
<script setup>
const checked = ref(false)
</script>
Custom Icons
<template>
<UCheckbox
v-model="checked"
label="Custom icons"
icon="i-heroicons-heart"
indeterminate-icon="i-heroicons-minus"
/>
</template>
<script setup>
const checked = ref(false)
</script>
Slots
Customize the label and description using slots:
<template>
<UCheckbox v-model="checked">
<template #label>
<span class="font-bold">Custom Label</span>
</template>
<template #description>
<span class="text-sm">Custom description content</span>
</template>
</UCheckbox>
</template>
<script setup>
const checked = ref(false)
</script>
Props
modelValue
boolean | 'indeterminate'
The controlled checked state of the checkbox. Can be bound with v-model.
defaultValue
boolean | 'indeterminate'
The default checked state when initially rendered. Use when you do not need to control the state.
The label text for the checkbox.
The description text displayed below the label.
The color theme of the checkbox.
The visual variant of the checkbox.
The size of the checkbox. Options: sm, md, lg.
Position of the checkbox indicator. Options: start, end.
The icon displayed when checked. Defaults to appConfig.ui.icons.check.
The icon displayed when the checkbox is indeterminate. Defaults to appConfig.ui.icons.minus.
When true, prevents user interaction with the checkbox.
When true, indicates that the checkbox must be checked.
The name of the checkbox for form submission.
The value of the checkbox when used in a form.
The id attribute of the checkbox input element.
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.
Events
Emitted when the checkbox state changes.
@update:modelValue
(value: boolean | 'indeterminate') => void
Emitted when the checked state changes.
Slots
Customize the label content.
Customize the description content.