RadioList

A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Radio List

A group of options where only one can be selected at a time. All options are visible at once, making it easy to compare choices. Use it when users need to pick one option from a small set.

Prop	Type	Default	Description
label *	string		Label text for the radio group (always rendered for accessibility).
value *	string		The currently selected value.
onChange *	(value: string) => void		Callback fired when the selected value changes.
children *	ReactNode		RadioListItem elements.
isLabelHidden	boolean	false	Whether to visually hide the label.
description	string		Description text displayed below the label.
orientation	'vertical' \| 'horizontal'	'vertical'	Layout direction of the radio items.
isDisabled	boolean	false	Whether all radio items are disabled.
htmlName	string		The HTML name attribute shared by the radio inputs, useful for form submissions. When omitted, a unique internal name still groups the radios.
disabledMessage	string		Explains why the group is disabled. Applies to the whole-group disabled state (isDisabled), not per item. With isDisabled, shows a tooltip on hover/keyboard focus and keeps the radios focusable via aria-disabled (selection stays blocked). Use this instead of wrapping a disabled RadioList in Tooltip. Disabled controls swallow the hover events an external Tooltip needs.
isRequired	boolean	false	Whether the radio group is required.
isOptional	boolean	false	Whether the field is optional (mutually exclusive with isRequired).
status	{type: 'warning' \| 'error' \| 'success', message?: string}		Status indicator ({ type, message }).
size	'sm' \| 'md'	'md'	Size of the radio controls.
labelTooltip	string		Tooltip text for an info icon next to the label.
width	SizeValue		Width of the field (number = pixels, string used as-is, e.g. "100%"). Sizes the whole field (label, control, and status) so they stay aligned.
containerXstyle	StyleXStyles		StyleX styles for the field container (label, control, and status together). No effect inside InputGroup (style the InputGroup instead) or in a `horizontal-labels` FormLayout. Root `xstyle`, `className`, and `style` are not accepted.
containerClassName	string		Class name for the field container. Same targeting as `containerXstyle`.
containerStyle	CSSProperties		Inline styles for the field container. Same targeting as `containerXstyle`.
controlXstyle	StyleXStyles		StyleX styles for the visual control box: the element that paints the border and background and holds icons and end controls. Never the native input.
controlClassName	string		Class name for the visual control box.
controlStyle	CSSProperties		Inline styles for the visual control box.

Usage guidance

Keep the number of options small: typically 2 to 7 choices.
Use clear, concise labels that differentiate each option at a glance.
Pre-select a default option when there's a sensible default; don't leave the group empty unless the choice is optional.
Avoid: Use when multiple selections are needed; use CheckboxList instead.
Avoid: Use for long lists; use Selector for better discoverability.
Avoid: Use horizontal layout with more than 4 options; it wraps awkwardly.
Avoid: Wrap a disabled RadioList in Tooltip to explain why it is disabled; disabled controls swallow the hover events the wrapper needs. Use the disabledMessage prop instead.

Theming API

{
  "targets": [
    {
      "className": "astryx-radio-list",
      "visualProps": [
        "orientation",
        "size"
      ]
    },
    {
      "className": "astryx-radio-list-item",
      "visualProps": [
        "size"
      ],
      "states": [
        "selected",
        "disabled"
      ]
    },
    {
      "className": "astryx-radio-indicator",
      "visualProps": [
        "size"
      ],
      "states": [
        "checked",
        "disabled"
      ]
    },
    {
      "className": "astryx-radio-indicator-dot",
      "visualProps": [
        "size"
      ]
    }
  ]
}

RadioListItem

Accessibility

Radio circle: The circle edge (unselected) and fill (selected) must have at least 3:1 contrast with the surface behind them. For Hover and Pointer down, measure the final colors after the tint and the pressed overlay are applied. — 3:1

Anatomy

Header: Optional heading above the radio list.
Children: The radio list items rendered as selectable options.
Label/Value: The text label and associated value for each radio item.

Radio List Item

Individual radio item with label, description, and content slots.

Prop	Type	Default	Description
label *	ReactNode		Primary label for the radio item. Rich labels may contain links or buttons, which keep their own behavior without selecting the item. The label text names the radio; use aria-label only when that text is absent, or retain every visible label word in the override.
aria-label	string		Plain-text accessible name for the radio, applied to the control rather than the row. It overrides the name derived from the label. Use it when a rich label has no visible text; otherwise retain every visible label word.
value *	string		Value of this radio item.
description	ReactNode		Secondary content displayed below the label. Links and buttons keep their own click behaviour — the row only delegates clicks from its non-interactive surface to the radio.
isDisabled	boolean	false	Whether this individual radio item is disabled.
startContent	ReactNode		Content to render before the radio circle.
endContent	ReactNode		Content to render after the label.

Examples

Radio List Item: Radio list items with labels, descriptions, and different states including disabled.
Radio List:
RadioList — Horizontal Layout: Radio list with horizontal orientation for compact selections.
RadioListItem — Basic: Radio items with labels and descriptions inside a controlled RadioList. Use for single-choice option groups like shipping methods.
RadioList — Pricing Tier: Radio list with pricing info in end content for plan selection.
RadioList — With Descriptions: Radio list with descriptions on the group and each item.
RadioList — With Validation: Required radio list with an error message when nothing is selected.