Radio

Stable

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

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.

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>

With description

You can add description text below the radio label using the description prop or the description slot.

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

const model = ref('Standard')
</script>

<template>
  <div class="w-80">
    <HRadioGroup v-model="model">
      <HRadio
        value="Standard"
        description="Standard delivery takes 3-5 business days."
      >
        Standard Delivery
      </HRadio>
      <HRadio
        value="Express"
        description="Express delivery takes 1-2 business days."
      >
        Express Delivery
      </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 radio buttons vertically

Use with caution

Lay out radio buttons 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 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 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.