# Radio Group

**An easily stylable radio button component.**

**Reference:** [View Source](https://github.com/jramke/fluid-primitives/tree/main/Resources/Private/Primitives/RadioGroup) · [Zag.js Docs](https://zagjs.com/components/react/radio-group)

**RadioGroup.html**

```html
<f:variable name="items" value="{
    0: { value: 'option1', text: 'Option 1' },
    1: { value: 'option2', text: 'Option 2' },
    2: { value: 'option3', text: 'Option 3' }
}" />

<ui:radioGroup.root defaultValue="option2">
    <ui:radioGroup.label>Choose an option:</ui:radioGroup.label>
    <f:for each="{items}" as="item">
        <ui:radioGroup.item value="{item.value}">
            <ui:radioGroup.itemControl />
            <ui:radioGroup.itemText>{item.text}</ui:radioGroup.itemText>
        </ui:radioGroup.item>
    </f:for>
</ui:radioGroup.root>

```

**RadioGroup.ts**

```ts
import { mountAll } from 'fluid-primitives';
import { RadioGroup } from 'fluid-primitives/radio-group';

mountAll('radioGroup', ({ props }) => {
    const radioGroup = new RadioGroup(props);
    radioGroup.init();
    return radioGroup;
});

```

## Features

- Full keyboard navigation support
- Supports horizontal and vertical orientations
- Syncs with native form elements for proper form submission
- Works with Field component for form integration

## Installation

```bash
typo3 ui:add radio-group
```

Or copy the files manually from GitHub (https://github.com/jramke/fluid-primitives.com/tree/main/packages/docs/Resources/Private/Registry/RadioGroup) into your project.

Read more about installing [Components and Primitives](/docs/core-concepts/primitives.md).

## Examples

### Disabled Items

Disable specific radio options.

**RadioGroup.html**

```html
<ui:radioGroup.root defaultValue="available">
    <ui:radioGroup.label>Select plan:</ui:radioGroup.label>
    <ui:radioGroup.item value="available">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Available Plan</ui:radioGroup.itemText>
    </ui:radioGroup.item>
    <ui:radioGroup.item value="unavailable" disabled="{true}">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Unavailable Plan</ui:radioGroup.itemText>
    </ui:radioGroup.item>
</ui:radioGroup.root>

```

### Disabled Group

Disable the entire radio group.

**RadioGroup.html**

```html
<ui:radioGroup.root disabled="{true}" defaultValue="option1">
    <ui:radioGroup.label>Disabled group:</ui:radioGroup.label>
    <ui:radioGroup.item value="option1">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Option 1</ui:radioGroup.itemText>
    </ui:radioGroup.item>
    <ui:radioGroup.item value="option2">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Option 2</ui:radioGroup.itemText>
    </ui:radioGroup.item>
</ui:radioGroup.root>

```

### No Default Value

Start with no option selected by default.

**RadioGroup.html**

```html
<ui:radioGroup.root>
    <ui:radioGroup.label>Select your gender:</ui:radioGroup.label>
    <ui:radioGroup.item value="female">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Female</ui:radioGroup.itemText>
    </ui:radioGroup.item>
    <ui:radioGroup.item value="male">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Male</ui:radioGroup.itemText>
    </ui:radioGroup.item>
    <ui:radioGroup.item value="diverse">
        <ui:radioGroup.itemControl />
        <ui:radioGroup.itemText>Diverse</ui:radioGroup.itemText>
    </ui:radioGroup.item>
</ui:radioGroup.root>
```

## API Reference

### radioGroup.root

Provides shared radio group state and semantics. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `defaultValue` | `string` | No | `-` | The initial value of the checked radio when rendered. Use when you don't need to control the value of the radio group. Inherited from a surrounding field when available. |
| `name` | `string` | No | `-` | The name of the input fields in the radio. Useful for form submission. Inherited from a surrounding field when available. |
| `form` | `string` | No | `-` | The associate form of the underlying input. |
| `disabled` | `boolean` | No | `-` | If `true`, the radio group will be disabled. Inherited from a surrounding field when available. |
| `readOnly` | `boolean` | No | `-` | Whether the radio group is read-only. Inherited from a surrounding field when available. |
| `required` | `boolean` | No | `-` | If `true`, the radio group is marked as required. Inherited from a surrounding field when available. |
| `orientation` | `Enum\Orientation` | No | `Vertical` | Orientation of the radio group. |
| `invalid` | `boolean` | No | `-` | If `true`, the radio group is marked as invalid. Inherited from a surrounding field when available. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `rootId` | `string` | No | `-` | The root ID of the component, used for hydration and identification. |
| `ids` | `array` | No | `[]` | The IDs of of the component parts for composition. |
| `controlled` | `boolean` | No | `false` | If true, the component is meant to be initialized manually inside another component |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-scope` | radio-group |
| `data-part` | root |
| `data-orientation` | The orientation of the radio-group |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-required` | Present when required |

### radioGroup.label

Labels the radio group. Renders a `<span>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-scope` | radio-group |
| `data-part` | label |
| `data-orientation` | The orientation of the label |
| `data-disabled` | Present when disabled |
| `data-invalid` | Present when invalid |
| `data-required` | Present when required |

### radioGroup.item

Wraps a single radio item and makes it clickable. Renders a `<label>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `value` | `string` | Yes | `-` | The value of the radio item. |
| `disabled` | `boolean` | No | `-` | Whether the radio item is disabled. |
| `invalid` | `boolean` | No | `-` | Whether the radio item is invalid. |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### radioGroup.itemHiddenInput

Provides the native radio input for form submission. Renders an `<input>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### radioGroup.itemControl

Displays the visual radio control. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-scope` | radio-group |
| `data-part` | item-control |
| `data-active` | Present when active or pressed |

### radioGroup.itemText

Displays the visible label text for a radio item. Renders a `<span>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

### radioGroup.indicator

Displays the moving selection indicator. Renders a `<div>` element.

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `asChild` | `boolean` | No | `-` | If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props. |
| `class` | `string` | No | `-` | The CSS class(es) to be applied to the component. |
| `attributes` | `array` | No | `[]` | Additional attributes that should be rendered on the component where ui:attributes is used. |

#### Rendered data attributes

| Attribute | Description |
| --- | --- |
| `data-scope` | radio-group |
| `data-part` | indicator |
| `data-disabled` | Present when disabled |
| `data-orientation` | The orientation of the indicator |

### Machine JavaScript API

| Name | Type | Description |
| --- | --- | --- |
| `value` | `string \| null` | The current value of the radio group |
| `setValue` | `(value: string) => void` | Function to set the value of the radio group |
| `clearValue` | `VoidFunction` | Function to clear the value of the radio group |
| `focus` | `VoidFunction` | Function to focus the radio group |
| `getItemState` | `(props: ItemProps) => ItemState` | Returns the state details of a radio input |

### Accessibility

| Key | Description |
| --- | --- |
| `Tab`  | Moves focus to either the checked radio item or the first radio item in the group. |
| `Space`  | When focus is on an unchecked radio item, checks it. |
| `ArrowDown`  | Moves focus and checks the next radio item in the group. |
| `ArrowRight`  | Moves focus and checks the next radio item in the group. |
| `ArrowUp`  | Moves focus to the previous radio item in the group. |
| `ArrowLeft`  | Moves focus to the previous radio item in the group. |

## Anatomy

```html
<primitives:radioGroup.root>
    <primitives:radioGroup.item>
        <primitives:radioGroup.itemControl />
        <primitives:radioGroup.itemText />
        <primitives:radioGroup.itemHiddenInput />
    </primitives:radioGroup.item>
    <primitives:radioGroup.indicator />
</primitives:radioGroup.root>
```