Checkbox

Stable

Checkboxes allow users to select none, one, or multiple independent options from a list.

A checkbox can also be used to display a single option that may require explicit acknowledgement or consent before submission.

<script setup lang="ts">
import { HCheckbox } from '@holistics/design-system'
import { ref } from 'vue'

const checked = ref(false)
</script>

<template>
  <div class="flex flex-wrap items-center gap-x-4 gap-y-2">
    <HCheckbox
      v-model="checked"
      label="Remember me"
    />

    <HCheckbox
      v-model="checked"
    />

    <HCheckbox
      v-model="checked"
      label="Disabled"
      disabled
    />
  </div>
</template>

Anatomy

1. Checkbox: shows the checked or unchecked state
2. Label: describes the option that users can select
3. Information icon (optional): provides additional context on hover

States

Usage guidelines

When to use

Use checkboxes when:

• Users can select one or more options from a list of 7 or fewer related items.
• Explicit confirmation is required before applying or submitting a change.

Consider alternatives

• To allow only one selection from a list of options, use Radio.
• To allow users to turn a setting on or off with immediate effect, use Switch.
• To avoid overwhelming users when there are more than 7 options, group related options or use Select.

Best practices

Alignment

When possible, arrange the checkbox and radio button groups vertically for easier reading. Use a horizontal layout only if there is limited vertical space, limit them to three items, and keep labels short with clear spacing.

Do

Lay out checkboxes vertically

Use with cautions

Lay out checkboxes horizontally when labels are short, with enough spacing to keep each option distinct.

Nested group

Checkboxes can be nested when a parent-child relationship is needed. Avoid nesting more than one level deep.

• Selecting the parent checkbox selects all child checkboxes.
• Deselecting the parent checkbox deselects all child checkboxes.

When only some child options are selected, display the parent checkbox in an indeterminate state.

Do

Use an indeterminate state

Don’t

Lack indeterminate state

Disabled state

Use a disabled state when an option or group is temporarily unavailable due to system constraints, permissions, or prior selections.

Display a Tooltip on hover to provide a clear reason why an option or group is disabled, and place the explanation near the disabled control

Pre-select

Pre-selection helps users move faster, but increases the risk of unintentional selection.

Use pre-selection only for clear defaults or system-recommended options that are safe, non-destructive, and commonly used.

Do

Leave options unselected by default to avoid accidental choices

Do

Pre-select options only when the default is safe, common, and unlikely to cause unintended outcomes

Listing

In some cases, ordering options intentionally can improve scannability and decision-making.

Common patterns include ordering by:

• most likely to least likely to be selected
• simplest to most complex operation
• least to most risk

Content

Group Labels

Group labels provide context for the set of options below and help users distinguish between checkbox groups.

• Use sentence case
• Keep it concise (2–5 words maximum)

Helper text

Use helper text to provide additional context or instructions.

Checkbox label

Describe what selecting each checkbox will do.

• Use sentence case
• Use parallel structure across options
• Use active voice
• Use positive wording
• Do not use punctuation at the end of labels

Error messages

Display when validation fails.

Be specific and actionable: Explain what's wrong and how to fix it.

API

Pass-through: <div>

What does this mean?

All props, events, and attrs that are not specified in the tables below will be passed to the element/component described above.

Props

Name	Type	Description
modelValue	boolean
label	string
description	string
name	string
value	any
disabled	boolean
required	boolean

Events

Name	Parameters	Description
@update:modelValue	[value: boolean]

Slots

Name	Scoped	Description
#default	any
#description	any