Radio

Radio and RadioGroup provide mutually exclusive selection for property panels, settings forms, and editor toolbars. Radios share a name so the browser handles single-value form submission natively.

Live Preview

Import

import { Radio, RadioGroup } from 'entangle-ui';

When to use

| Component | Use when | | --------------------------- | --------------------------------------------------------------------------- | | Radio | 2–5 mutually exclusive options that should all be visible at once. | | Checkbox | A boolean toggle, or independent multi-selection. | | Select | 6+ options, or a dynamic / large choice space. | | SegmentedControl (soon) | Toolbar-density mutually exclusive states without surrounding form context. |

Standalone Radio

A single Radio works without a surrounding RadioGroup and supports both controlled and uncontrolled modes.

<Radio value="aa" label="Anti-aliasing" defaultChecked />

Sizes

<Radio size="sm" value="sm" label="Small" />
<Radio size="md" value="md" label="Medium" />
<Radio size="lg" value="lg" label="Large" />

| Size | Outer | Inner dot | | ---- | ----- | --------- | | sm | 12px | 6px | | md | 14px | 6px | | lg | 16px | 8px |

States

<Radio value="off" label="Off (unchecked)" />
<Radio value="on" defaultChecked label="On (checked)" />
<Radio value="dis-off" disabled label="Disabled — off" />
<Radio value="dis-on" disabled defaultChecked label="Disabled — on" />
<Radio value="error" error label="Error state" />

RadioGroup

RadioGroup manages exclusive selection across child Radio components via React Context. The group’s name, size, disabled, and error override the corresponding props on individual radios.

Vertical

<RadioGroup label="Coordinate space" defaultValue="local">
  <Radio value="local" label="Local" />
  <Radio value="world" label="World" />
  <Radio value="parent" label="Parent" />
  <Radio value="screen" label="Screen" />
</RadioGroup>

Horizontal

<RadioGroup
  label="Coordinate space"
  orientation="horizontal"
  defaultValue="local"
>
  <Radio value="local" label="Local" />
  <Radio value="world" label="World" />
  <Radio value="parent" label="Parent" />
</RadioGroup>

Controlled

Pass value and onChange for controlled mode. The handler receives the new value as a string.

const [space, setSpace] = useState('local');

<RadioGroup label="Coordinate space" value={space} onChange={setSpace}>
  <Radio value="local" label="Local" />
  <Radio value="world" label="World" />
  <Radio value="parent" label="Parent" />
</RadioGroup>;

Required & Error

<RadioGroup
  label="Coordinate space"
  required
  error
  errorMessage="Selection required to continue"
>
  <Radio value="local" label="Local" />
  <Radio value="world" label="World" />
  <Radio value="parent" label="Parent" />
</RadioGroup>

In a property panel

<PropertyRow label="Coordinate space">
  <RadioGroup
    orientation="horizontal"
    size="sm"
    value={space}
    onChange={setSpace}
  >
    <Radio value="local" label="Local" />
    <Radio value="world" label="World" />
    <Radio value="parent" label="Parent" />
  </RadioGroup>
</PropertyRow>

Accessibility

• Radio renders a native <input type="radio"> with role="radio" and aria-checked.
• RadioGroup renders role="radiogroup" with aria-labelledby, aria-required, aria-invalid, aria-disabled, and aria-orientation.
• Helper text and error messages are linked to the input via aria-describedby.
• Tab moves focus to the group; Space selects the focused radio.
• Arrow keys (Up / Down / Left / Right) move selection between radios that share a name. This is native browser behavior — RadioGroup propagates name automatically.
• The label wraps the input so clicking the label toggles the radio.
• Animations honor prefers-reduced-motion: the inner dot snaps instead of scaling.

Radio props

Prop	Type	Default	Description
value	string	—	Value of this radio option. Used by RadioGroup for selection and as the input value attribute.
checked	boolean	—	Whether this radio is selected (controlled, standalone). Ignored when inside a RadioGroup.
defaultChecked	boolean	false	Default checked state (uncontrolled, standalone). Ignored inside a RadioGroup.
label	string	—	Label text displayed next to the radio.
labelPosition	'left' | 'right'	'right'	Position of the label relative to the radio.
size	'sm' | 'md' | 'lg'	'md'	Radio size. Inside a RadioGroup, the group size overrides this prop.
disabled	boolean	false	Whether the radio is disabled. Inside a RadioGroup, the group value overrides this prop.
error	boolean	false	Visual error state. Inside a RadioGroup, the group value overrides this prop.
helperText	string	—	Helper text displayed below the radio (standalone use only).
errorMessage	string	—	Error message displayed when error is true (standalone use only).
name	string	—	Form name attribute. Inside a RadioGroup, the group name overrides this prop.
onChange	(value: string, event: ChangeEvent<HTMLInputElement>) => void	—	Change handler. Standalone Radio fires when toggled on; rarely used inside a RadioGroup.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLInputElement>	—	Ref to the underlying input element.

RadioGroup props

Prop	Type	Default	Description
value	string	—	Currently selected value (controlled).
defaultValue	string	—	Default selected value (uncontrolled).
label	string	—	Group label rendered above the radios.
helperText	string	—	Helper text displayed below the group.
disabled	boolean	false	Disables the entire group.
error	boolean	false	Whether the group has an error state.
errorMessage	string	—	Error message displayed when error is true. Replaces helperText.
required	boolean	false	Whether selection is required. Sets aria-required on the group.
orientation	'horizontal' | 'vertical'	'vertical'	Layout direction for the radios.
spacing	number | string	2	Spacing between radios. Number maps to the theme spacing scale; strings pass through unchanged.
name	string	—	Form name attribute applied to all child radios.
size	'sm' | 'md' | 'lg'	'md'	Size applied to all child radios.
onChange	(value: string) => void	—	Change handler — fires when any radio in the group is selected.
children	ReactNode	—	Typically a list of Radio components.
className	string	—	Additional CSS class names.
style	CSSProperties	—	Inline styles.
testId	string	—	Test identifier for automated testing.
ref	Ref<HTMLDivElement>	—	Ref to the underlying wrapper element.