Lets users pick exactly one option from a small visible set
Installation
-
Install the package
terminal npm install @hashintel/ds-components -
Import the component
app.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
- Do: Use RadioGroup when users must pick exactly one of 2–5 mutually exclusive options
- Do: Use it when seeing every option at once helps the decision — all choices stay visible, unlike Select.
- Do: Give the group a sensible default selection —
valueis required and must match one of the item values.
When not to use
- Don't: Don't use it for large amounts of options — use Select, or Combobox when the list needs search.
- Don't: Don't use it when users may pick several options — use CheckboxGroup.
- Don't: Don't use it for an on/off choice — use Toggle, or a single Checkbox in forms.
- Don't: Don't use it for a mode switch that applies instantly in toolbars or chrome — use SegmentedControl; RadioGroup belongs in forms.
Examples
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.
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.
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.
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.
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.
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.
Label placement
Set labelPlacement: "left" on items to put the label before the circle.
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.
Behavior
onFocusandonBlurfire only when focus enters or leaves the group as a whole — moving between options doesn't retrigger them.- Options share one
namefor form submission, auto-generated unless you pass one. - Users can move the selection but never clear it —
onChangealways receives an option value. requiredsetsaria-requiredon the group but doesn't enable native form validation — validate on submit and setinvalid.
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
Options are native radio inputs; together they implement the WAI-ARIA radio group pattern.
What RadioGroup provides
- Renders a
role="radiogroup"container, witharia-requiredwhen a selection is required andaria-orientationmatching the layout.
What you must do
- Always name the group: a visible label via
Form.Fieldwithas="legend", oraria-labelwhen the surrounding context already says what the choice is. - Pair
invalidwith an error message, e.g.Form.Field'serrors— 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
| Prop | Type | Description |
|---|---|---|
| items | (Omit<{ label?: ReactNode; labelPlacement?: "left" | "right" | undefined; labelAlign?: "top" | "center" | undefined; tone?: "neutral" | "brand" | "success" | undefined; htmlValue?: string | undefined; } & { ...; } & SharedInputAndFieldProps & AriaAttributes, "size" | ... 6 more ... | "htmlForId"> & { ...; })[] | |
| value | string | The input value |
| onChange | (value: NoInfer<ValueType>) => void | The onChange handler |
| layout | "inline" | "block" | "blockWithBorder" default: "block" | How the options are arranged: block stacks them vertically, inline lays them out in a row, blockWithBorder stacks them inside a bordered container with a divider between options. |
| size | "xxs" | "xs" | "sm" | "md" | "lg" default: "md" | The size (height) of the element |
| disabled | boolean | Set to show the input as disabled |
| autoFocus | boolean | "never" | Set to true to make the element focused on mount or 'never' to prevent the item being auto-focused |
| onFocus | FocusEventHandler<HTMLInputElement> | The onFocus handler |
| onBlur | FocusEventHandler<HTMLInputElement> | The onBlur handler |
| required | boolean | Marks the input as required: sets the native required attribute, so assistive technology announces it and form validation blocks empty submits. Purely functional — the input looks unchanged; pair it with Form.Field's required for the visible mark. |
| name | string | The name of the input |
| invalid | boolean | Set to show the input as invalid |
Was this page helpful?