# RadioGroup (/components/radio-group)

<ReferenceLinks
  links={[
    { label: "Source", href: meta.links.source, iconName: "code" },
    { label: "Stories", href: meta.links.stories },
  ]}
/>

<Stage code={"<RadioGroup\n  aria-label=\"Entity visibility\"\n  items={[\n    { value: \"private\", label: \"Only me\" },\n    { value: \"workspace\", label: \"Everyone in the workspace\" },\n    { value: \"public\", label: \"Anyone with the link\" },\n  ]}\n  value=\"workspace\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  layout=\"blockWithBorder\"\n  aria-label=\"Sync frequency\"\n  items={[\n    { value: \"hourly\", label: \"Hourly\" },\n    { value: \"daily\", label: \"Daily\" },\n    { value: \"weekly\", label: \"Weekly\" },\n  ]}\n  value=\"daily\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      aria-label="Entity visibility"
      items={[
        { value: "private", label: "Only me" },
        { value: "workspace", label: "Everyone in the workspace" },
        { value: "public", label: "Anyone with the link" },
      ]}
      value="workspace"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      layout="blockWithBorder"
      aria-label="Sync frequency"
      items={[
        { value: "hourly", label: "Hourly" },
        { value: "daily", label: "Daily" },
        { value: "weekly", label: "Weekly" },
      ]}
      value="daily"
      onChange={noop}
    />
  </DemoState>
</Stage>

## Installation [#installation]

1. Install the package.

```sh
npm install @hashintel/ds-components
```

2. Import the component.

```tsx
import { useState } from "react";

import { RadioGroup } from "@hashintel/ds-components";

export const EntityVisibility = () => {
  const [visibility, setVisibility] = useState<
    "private" | "workspace" | "public"
  >("workspace");

  return (
    <RadioGroup
      aria-label="Entity visibility"
      items={[
        { value: "private", label: "Only me" },
        { value: "workspace", label: "Everyone in the workspace" },
        { value: "public", label: "Anyone with the link" },
      ]}
      value={visibility}
      onChange={setVisibility}
    />
  );
};
```

### When to use [#when-to-use]

<DoList
  items={[
    "Use RadioGroup when users must pick exactly one of 2–5 mutually exclusive options",
    "Use it when seeing every option at once helps the decision — all choices stay visible, unlike Select.",
    <Fragment key="0">
      Give the group a sensible default selection — <code>value</code> is
      required and must match one of the item values.
    </Fragment>,
  ]}
/>

### When not to use [#when-not-to-use]

<DontList
  items={[
    "Don't use it for large amounts of options — use Select, or Combobox when the list needs search.",
    "Don't use it when users may pick several options — use CheckboxGroup.",
    "Don't use it for an on/off choice — use Toggle, or a single Checkbox in forms.",
    "Don't use it for a mode switch that applies instantly in toolbars or chrome — use SegmentedControl; RadioGroup belongs in forms.",
  ]}
/>

## Examples [#examples]

### Basic [#basic]

RadioGroup is controlled: `value` holds the selected option's value and `onChange` receives the newly selected one. Each item takes a unique `value` plus any Radio props, such as `label`, `disabled`, or `tone`.

<Stage code={"<RadioGroup\n  aria-label=\"Flow trigger\"\n  items={[\n    { value: \"manual\", label: \"Manual\" },\n    { value: \"scheduled\", label: \"Scheduled\" },\n    { value: \"entity-update\", label: \"On entity update\" },\n  ]}\n  value=\"scheduled\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      aria-label="Flow trigger"
      items={[
        { value: "manual", label: "Manual" },
        { value: "scheduled", label: "Scheduled" },
        { value: "entity-update", label: "On entity update" },
      ]}
      value="scheduled"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Disabled [#disabled]

Set `disabled` on the group to lock every option, or `disabled: true` on an item to lock just that one. Explain why in nearby text — a disabled option doesn't say.

<Stage code={"<RadioGroup\n  disabled\n  aria-label=\"Sync frequency\"\n  items={[\n    { value: \"hourly\", label: \"Hourly\" },\n    { value: \"daily\", label: \"Daily\" },\n    { value: \"weekly\", label: \"Weekly\" },\n  ]}\n  value=\"daily\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  aria-label=\"Teammate role\"\n  items={[\n    { value: \"viewer\", label: \"Viewer\" },\n    { value: \"editor\", label: \"Editor\" },\n    { value: \"admin\", label: \"Admin\", disabled: true },\n  ]}\n  value=\"editor\"\n  onChange={() => {}}\n/>"}>
  <RadioGroup
    disabled
    aria-label="Sync frequency"
    items={[
      { value: "hourly", label: "Hourly" },
      { value: "daily", label: "Daily" },
      { value: "weekly", label: "Weekly" },
    ]}
    value="daily"
    onChange={noop}
  />
  <DemoState>
    <RadioGroup
      aria-label="Teammate role"
      items={[
        { value: "viewer", label: "Viewer" },
        { value: "editor", label: "Editor" },
        { value: "admin", label: "Admin", disabled: true },
      ]}
      value="editor"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Invalid [#invalid]

Set `invalid` when the current selection fails validation — for example, a choice the workspace's policy forbids. The error styling appears on the selected option; pair it with an error message, since the styling alone doesn't say what's wrong.

<Stage code={"<RadioGroup\n  invalid\n  aria-label=\"Entity visibility\"\n  items={[\n    { value: \"private\", label: \"Only me\" },\n    { value: \"workspace\", label: \"Everyone in the workspace\" },\n    { value: \"public\", label: \"Anyone with the link\" },\n  ]}\n  value=\"public\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      invalid
      aria-label="Entity visibility"
      items={[
        { value: "private", label: "Only me" },
        { value: "workspace", label: "Everyone in the workspace" },
        { value: "public", label: "Anyone with the link" },
      ]}
      value="public"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Layouts [#layouts]

`block` (the default) stacks options for easy scanning. Use `blockWithBorder` for settings-style lists where each option reads as a row, and `inline` only for 2–3 short options where vertical space is tight.

<Stage code={"<RadioGroup\n  layout=\"block\"\n  aria-label=\"When duplicates are found\"\n  items={[\n    { value: \"keep-newest\", label: \"Keep newest values\" },\n    { value: \"keep-existing\", label: \"Keep existing values\" },\n    { value: \"review\", label: \"Review each conflict\" },\n  ]}\n  value=\"keep-newest\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  layout=\"blockWithBorder\"\n  aria-label=\"Sync frequency\"\n  items={[\n    { value: \"hourly\", label: \"Hourly\" },\n    { value: \"daily\", label: \"Daily\" },\n    { value: \"weekly\", label: \"Weekly\" },\n  ]}\n  value=\"daily\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  layout=\"inline\"\n  aria-label=\"Sort order\"\n  items={[\n    { value: \"ascending\", label: \"Ascending\" },\n    { value: \"descending\", label: \"Descending\" },\n  ]}\n  value=\"ascending\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      layout="block"
      aria-label="When duplicates are found"
      items={[
        { value: "keep-newest", label: "Keep newest values" },
        { value: "keep-existing", label: "Keep existing values" },
        { value: "review", label: "Review each conflict" },
      ]}
      value="keep-newest"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      layout="blockWithBorder"
      aria-label="Sync frequency"
      items={[
        { value: "hourly", label: "Hourly" },
        { value: "daily", label: "Daily" },
        { value: "weekly", label: "Weekly" },
      ]}
      value="daily"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      layout="inline"
      aria-label="Sort order"
      items={[
        { value: "ascending", label: "Ascending" },
        { value: "descending", label: "Descending" },
      ]}
      value="ascending"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Sizes [#sizes]

`size` scales the circles, labels, and spacing together, from `xxs` to `lg`; `md` is the default. Match the size of the surrounding form inputs.

<Stage code={"<RadioGroup\n  size=\"xxs\"\n  aria-label=\"xxs\"\n  items={[{ value: \"xxs\", label: \"xxs\" }]}\n  value=\"xxs\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  size=\"xs\"\n  aria-label=\"xs\"\n  items={[{ value: \"xs\", label: \"xs\" }]}\n  value=\"xs\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  size=\"sm\"\n  aria-label=\"sm\"\n  items={[{ value: \"sm\", label: \"sm\" }]}\n  value=\"sm\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  size=\"md\"\n  aria-label=\"md\"\n  items={[{ value: \"md\", label: \"md\" }]}\n  value=\"md\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  size=\"lg\"\n  aria-label=\"lg\"\n  items={[{ value: \"lg\", label: \"lg\" }]}\n  value=\"lg\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      size="xxs"
      aria-label="xxs"
      items={[{ value: "xxs", label: "xxs" }]}
      value="xxs"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      size="xs"
      aria-label="xs"
      items={[{ value: "xs", label: "xs" }]}
      value="xs"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      size="sm"
      aria-label="sm"
      items={[{ value: "sm", label: "sm" }]}
      value="sm"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      size="md"
      aria-label="md"
      items={[{ value: "md", label: "md" }]}
      value="md"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      size="lg"
      aria-label="lg"
      items={[{ value: "lg", label: "lg" }]}
      value="lg"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Tones [#tones]

Items take a `tone` that colors their selected state: `neutral` (the default), `brand`, or `success`. Use one tone across a group — mixed tones read as different meanings.

<Stage code={"<RadioGroup\n  aria-label=\"Neutral tone\"\n  items={[{ value: \"neutral\", label: \"Neutral\", tone: \"neutral\" }]}\n  value=\"neutral\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  aria-label=\"Brand tone\"\n  items={[{ value: \"brand\", label: \"Brand\", tone: \"brand\" }]}\n  value=\"brand\"\n  onChange={() => {}}\n/>\n<RadioGroup\n  aria-label=\"Success tone\"\n  items={[{ value: \"success\", label: \"Success\", tone: \"success\" }]}\n  value=\"success\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      aria-label="Neutral tone"
      items={[{ value: "neutral", label: "Neutral", tone: "neutral" }]}
      value="neutral"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      aria-label="Brand tone"
      items={[{ value: "brand", label: "Brand", tone: "brand" }]}
      value="brand"
      onChange={noop}
    />
  </DemoState>
  <DemoState>
    <RadioGroup
      aria-label="Success tone"
      items={[{ value: "success", label: "Success", tone: "success" }]}
      value="success"
      onChange={noop}
    />
  </DemoState>
</Stage>

### Label placement [#label-placement]

Set `labelPlacement: "left"` on items to put the label before the circle.

<Stage code={"<RadioGroup\n  layout=\"blockWithBorder\"\n  aria-label=\"Default entity view\"\n  items={[\n    { value: \"table\", label: \"Table\", labelPlacement: \"left\" },\n    { value: \"board\", label: \"Board\", labelPlacement: \"left\" },\n    { value: \"graph\", label: \"Graph\", labelPlacement: \"left\" },\n  ]}\n  value=\"table\"\n  onChange={() => {}}\n/>"}>
  <DemoState>
    <RadioGroup
      layout="blockWithBorder"
      aria-label="Default entity view"
      items={[
        { value: "table", label: "Table", labelPlacement: "left" },
        { value: "board", label: "Board", labelPlacement: "left" },
        { value: "graph", label: "Graph", labelPlacement: "left" },
      ]}
      value="table"
      onChange={noop}
    />
  </DemoState>
</Stage>

### With a group label [#with-a-group-label]

Wrap the group in `Form.Field` with `as="legend"` to give it a visible label, description, and error messages — `as="legend"` names the whole group rather than a single input.

<Stage code={"<Form.Field\n  as=\"legend\"\n  label=\"Entity visibility\"\n  description=\"Who can see entities you create\"\n>\n  <RadioGroup\n    items={[\n      { value: \"private\", label: \"Only me\" },\n      { value: \"workspace\", label: \"Everyone in the workspace\" },\n      { value: \"public\", label: \"Anyone with the link\" },\n    ]}\n    value=\"workspace\"\n    onChange={() => {}}\n  />\n</Form.Field>"}>
  <FormField
    as="legend"
    label="Entity visibility"
    description="Who can see entities you create"
  >
    <DemoState>
      <RadioGroup
        items={[
          { value: "private", label: "Only me" },
          { value: "workspace", label: "Everyone in the workspace" },
          { value: "public", label: "Anyone with the link" },
        ]}
        value="workspace"
        onChange={noop}
      />
    </DemoState>
  </FormField>
</Stage>

## Behavior [#behavior]

- `onFocus` and `onBlur` fire only when focus enters or leaves the group as a whole — moving between options doesn't retrigger them.
- Options share one `name` for form submission, auto-generated unless you pass one.
- Users can move the selection but never clear it — `onChange` always receives an option value.
- `required` sets `aria-required` on the group but doesn't enable native form validation — validate on submit and set `invalid`.

## Content [#content]

- Write option labels as short, parallel phrases — sentence case, under 4 words, no end punctuation: "Hourly", "On entity update".
- Make options mutually exclusive and cover every case — add an explicit "Other" or "No preference" option rather than forcing a wrong fit.
- Order options logically — by likely frequency of use, or smallest to largest; alphabetically when there's no natural order.
- Let long labels wrap rather than truncating them — the circle stays aligned with the first line.

## Accessibility [#accessibility]

Options are native radio inputs; together they implement the [WAI-ARIA radio group pattern](https://www.w3.org/WAI/ARIA/apg/patterns/radio/).

### What RadioGroup provides [#what-radiogroup-provides]

- Renders a `role="radiogroup"` container, with `aria-required` when a selection is required and `aria-orientation` matching the layout.

### What you must do [#what-you-must-do]

- Always name the group: a visible label via `Form.Field` with `as="legend"`, or `aria-label` when the surrounding context already says what the choice is.
- Pair `invalid` with an error message, e.g. `Form.Field`'s `errors` — the red styling alone isn't perceivable by everyone.
- Explain disabled options in nearby text — a disabled radio doesn't say why it's unusable.

## API reference [#api-reference]

<PropsTable
  of={RadioGroup}
  defaults={{
    layout: '"block"',
    size: '"md"',
  }}
/>
