Radio

Stable

Radio buttons require users to make one selection from a group of options that are mutually exclusive.

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

const model = ref('Option 1')

const values = ['Option 1', 'Option 2', 'Option 3', 'Option 4']

</script>

<template>
  <div class="w-32">
    <div>Result: {{ model }}</div>
    <HRadioGroup
      v-model="model"
    >
      <HRadio
        v-for="value in values"
        :key="value"
        :value="value"
      >
        {{ value }}
      </HRadio>
    </HRadioGroup>
  </div>
</template>

A radio button may not be used on its own: it must be rendered in a group of related radio buttons using a Radio Group. Radio buttons cannot be unchecked, so only use radio buttons when a selection is required.

The Radio component supports the Roving Focus by default.

Anatomy

1. Radio button: 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

Mixed disabled state

This example will disable the individual option, but you can disable the entire group by setting the disabled prop on the Radio Group.

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

const model = ref('Option 1')

const values = ['Option 1', 'Option 2', 'Option 3', 'Option 4']

</script>

<template>
  <div class="w-32">
    <div>Result: {{ model }}</div>
    <HRadioGroup
      v-model="model"
    >
      <HRadio
        v-for="value in values"
        :key="value"
        :value="value"
        :disabled="value === 'Option 2'"
      >
        {{ value }}
      </HRadio>
    </HRadioGroup>
  </div>
</template>

Usage guidelines

When to use

Use radio buttons when users can only select one option from a list.

Consider alternatives

• To allow users to select none, one, or multiple options, use Checkbox
• 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, use Select

Best practices

Radio buttons are used in groups to select exactly one option.

Once selected, a radio button cannot be cleared - users must choose another option in the same group. Use radio buttons when a selection is required and mutually exclusive.

Do

Use checkboxes when no selection is allowed

Don’t

Use radio buttons when no selection is a valid state

‘None’ option

Include “None” as an option if users are allowed to omit a selection. This functions as an “unselect” option if users accidentally choose an option they don’t want or wish to omit a selection altogether.

Do

Include ‘None’ if users may need an unselected state, as users can’t unselect an option without selecting a new one

Don’t

Leave out ‘None’ if an unselected state is possible, as users may be forced to select an option they don’t want

Alignment

When possible, arrange the checkbox and radio button groups vertically for easier reading. Use a horizontal layout if there is limited vertical space, with a maximum of 3 items.

Do

Lay out checkboxes vertically

Use with cautions

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

Pre-select

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

Pre-select options by default, while ensuring the selected option is safe, non-destructive, and commonly used.

Do

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

Don’t

Pre-select options when the impact isn’t clearly safe or expected.

Listing

In some cases, ordering options intentionally can improve scanability 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 radio button groups.

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

Helper text

Use helper text to provide additional context or instructions.

Radio label

Describe what selecting each radio option will do.

• Use sentence case
• Use parallel structure across options
• Do not use punctuation at the end of labels
• Use positive wording
• Be mindful of:
  • Numeric choices that overlap (for example, Select age: 0-20, 20-40 — it's unclear which option to select if your age is 20).
  • Numeric choices that skip a number (for example, Select age: Below 20, Above 20 - there is no option to select if your age is 20).
  • If you can't have a list of all possible options, add an "Other" option.

Error messages

Display when validation fails. Be specific and actionable: Explain what's wrong and how to fix it.

HRadioGroup 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
orientation	"vertical" | "horizontal" = "vertical"
disabled	boolean = false
name	string
required	boolean = false
modelValue	unknown

Events

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

Slots

Name	Scoped	Description
#default	{}