Skip to main content
Skip to Content

Lets users pick exactly one option from a small visible set

Installation

  1. Install the package

    terminal
    npm install @hashintel/ds-components
  2. 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 — value is 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.

Entity visibilityWho can see entities you create

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

  • 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, with aria-required when a selection is required and aria-orientation matching the layout.

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

PropTypeDescription
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
onChange
(value: NoInfer<ValueType>) => void
layout
"inline" |⁠ "block" |⁠ "blockWithBorder"
default: "block"
size
"xxs" |⁠ "xs" |⁠ "sm" |⁠ "md" |⁠ "lg"
default: "md"
disabled
boolean
autoFocus
boolean |⁠ "never"
onFocus
FocusEventHandler<HTMLInputElement>
onBlur
FocusEventHandler<HTMLInputElement>
required
boolean
name
string
invalid
boolean

Was this page helpful?

On this page