# RadioList

- Page: https://jiguang132.com/resources/astryx/docs/radio-list
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

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

```bash
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](/resources/astryx/docs/getting-started).

## 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

```json
{
  "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.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt