# Radio group

A form element that enables users to select a single value from a list of options.

Tabs: [Guidelines](/components/web/radio-group/radio-group.guidelines.md) · [Code](/components/web/radio-group/radio-group.code.md)

- Supports required and disable states.

- Enforces that at least two options are presented.

- Compatible with our [Form control](/components/web/form-control/form-control.guidelines) component

- Adheres to [our form accessibility guidelines](/patterns/forms/forms.accessibility).

## When to use

Use radio groups when users need to select a single value from a small, predefined set of mutually exclusive options. For larger sets of options, consider using a [Select](/components/web/select/select.guidelines) component instead.

## Examples

Information:

We promote usage of this component in combination with our [Form control](/components/web/form-control/form-control.guidelines) component to maintain layout consistency and ensure form accessibility. The Form control supports advanced use cases such as [hint text](/components/web/form-control/form-control.guidelines#hint-text), [help popovers](/components/web/form-control/form-control.guidelines#help-popover) and [error messages](/components/web/form-control/form-control.guidelines#error).

### Label

The label of a form element should be clear and concise, ideally under three words. It should describe the value of the element and not what the user needs to do in order to fill it out properly.

Information:

**Never omit a label**. Form labels are required for accessibility purposes. However, it may be acceptable to [hide the label visually](/patterns/forms/forms.accessibility#hiding-a-label-visually) in certain cases.

```tsx
<FormControl>
    <FormControl.Label>Role</FormControl.Label>
    <FormControl.RadioGroup>
        <RadioButton value="employee" label="Employee" />
        <RadioButton value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

### Required or optional

Mark the minority of form elements in a form as required or optional. This helps users scan the form and understand what is required of them. Type out the word optional or required in the label. E.g. "Per purchase limit (optional)". Don't use asterisks or other symbols.

```tsx
<FormControl>
    <FormControl.Label>Role (required)</FormControl.Label>
    <FormControl.RadioGroup name="role" isRequired>
        <RadioButton value="employee" label="Employee" />
        <RadioButton value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

### Hint text

Use hint text to give users clear guidance for data entry. Keep it brief and avoid repeating the label or other form details. If it feels redundant, try removing it. We keep help text above the input field to have the reading order match the visual order, which is needed for screen readers.

```tsx
<FormControl>
    <FormControl.Label>Role</FormControl.Label>
    <FormControl.HintText>
        Select the role with the appropriate permissions for the user
    </FormControl.HintText>
    <FormControl.RadioGroup name="role">
        <RadioButton value="employee" label="Employee" />
        <RadioButton value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

### Help popover

Use help popovers to aid first-time users or to clarify complex concepts. The help popover can contain interactive content and may be used to provide links for further information.

```tsx
<FormControl>
    <FormControl.LabelWrapper>
        <FormControl.Label>Role</FormControl.Label>
        <FormControl.Help aria-label="Learn more about: Role">
            Pleo offers two user roles: Employee and Admin. Employees can manage their own expenses
            using Pleo cards and submit out-of-pocket reimbursements. Admins oversee company
            spending, manage user roles, configure integrations, and set spending limits.
        </FormControl.Help>
    </FormControl.LabelWrapper>
    <FormControl.RadioGroup>
        <RadioButton value="employee" label="Employee" />
        <RadioButton value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

### Error

Provide clear and helpful error messages that guide users toward a solution. Instead of merely stating the problem, ensure the message is specific and actionable. Avoid vague or shaming language.

> Individual radio buttons should not have its own error message or style.

```tsx
<FormControl>
    <FormControl.Label>Role (required)</FormControl.Label>
    <FormControl.RadioGroup>
        <RadioButton value="employee" label="Employee" />
        <RadioButton value="admin" label="Admin" />
    </FormControl.RadioGroup>
    <FormControl.Error>Choose your role</FormControl.Error>
</FormControl>
```

### Skeleton

Use a "skeleton" version of this component to display a loading state while data is being fetched. It provides a visual placeholder, giving users a preview of the UI structure before the actual content is loaded. This enhances the user experience by offering a more accurate representation of the final layout during data retrieval.

```tsx
<FormControl skeleton>
    <FormControl.Label>Role</FormControl.Label>
    <FormControl.RadioGroup>
        <RadioButton skeleton disabled value="employee" label="Employee" />
        <RadioButton skeleton disabled value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

### Disabled

Disable a form element to indicate that it’s currently unavailable. This can be used to maintain layout consistency and communicate that the element may become available later. If the form element will never be available in a given context, leave it out.

```tsx
<FormControl>
    <FormControl.Label>Role</FormControl.Label>
    <FormControl.RadioGroup>
        <RadioButton disabled value="employee" label="Employee" />
        <RadioButton disabled value="admin" label="Admin" />
    </FormControl.RadioGroup>
</FormControl>
```

## Accessibility

The implementation of this component has been informed by [our form accessibility guidelines](/patterns/forms/forms.accessibility).

## Best practices

Refer to our [Forms guidelines](/patterns/forms/forms.about) for general advice on forms structure, validation, and more.

## Related components

- [Checkbox](/components/web/checkbox/checkbox.guidelines): A form element that enables users to make a binary choice (checked/unchecked).
- [Choice tiles](/components/web/choice-tiles/choice-tiles.guidelines): Enable users to select a single value from a list of choices that support more complex content than regular radio buttons.
- [Form control](/components/web/form-control/form-control.guidelines): Form control displays a labelled input and, optionally, associated validation text, help popover, and/or hint text.
- [Segmented control](/components/web/segmented-control/segmented-control.guidelines): A hybrid somewhere between a button group, radio buttons, and tabs; segmented controls are used to switch between different options or views.
- [Select](/components/web/select/select.guidelines): A form element that enables users to select a single or multiple values from a list of options.