Radio Group

An easily stylable radio button component.

Choose an option: Option 1 Option 2 Option 3

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

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

Anatomy

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

Installation

typo3 ui:add radio-group

Read more about installing Components and Primitives.

Examples

Disabled Items

Disable specific radio options.

Select plan: Available Plan Unavailable Plan

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

Disabled group: Option 1 Option 2

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

Select your gender: Female Male Diverse

<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

The following tables cover the available props of the Fluid Primitives. For a full list of available client side props and methods, see the Zag.js Machine API.

radioGroup.root

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

Name	Description	Required	Default
`defaultValue`	`string` 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.	No	-
`name`	`string` The name of the input fields in the radio. Useful for form submission. Inherited from a surrounding field when available.	No	-
`form`	`string` The associate form of the underlying input.	No	-
`disabled`	`boolean` If `true`, the radio group will be disabled. Inherited from a surrounding field when available.	No	-
`readOnly`	`boolean` Whether the radio group is read-only. Inherited from a surrounding field when available.	No	-
`required`	`boolean` If `true`, the radio group is marked as required. Inherited from a surrounding field when available.	No	-
`orientation`	`Enum\Orientation` Orientation of the radio group.	No	Vertical
`invalid`	`boolean` If `true`, the radio group is marked as invalid. Inherited from a surrounding field when available.	No	-
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`rootId`	`string` The root ID of the component, used for hydration and identification.	No	-
`ids`	`array` The IDs of of the component parts for composition.	No	[]
`autoMount`	`boolean` Whether the client initializes the component on its own. Set it to false to mount it yourself with `mount()`	No	true
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

Attribute	Description
`data-radio-group-root`	<uid>
`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	Description	Required	Default
`attributes`	`array` Additional attributes that should be rendered on the component where ui:attributes is used.	No	[]
`asChild`	`boolean` If true the component uses its child only without the component template. Like Radix UI asChild or Base UI render props.	No	-
`class`	`string` The CSS class(es) to be applied to the component.	No	-

Rendered data attributes

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

Rendered data attributes

Attribute	Description
`data-radio-group-item`	<uid>
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-state`	"checked" \| "unchecked"
`data-hover`	Present when hovered
`data-invalid`	Present when invalid
`data-orientation`	The orientation of the item
`data-ssr`	Present when not rendered in the browser. Useful for ssr styling

radioGroup.itemHiddenInput

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

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

radioGroup.itemControl

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

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

Rendered data attributes

Attribute	Description
`data-radio-group-item-control`	<uid>
`data-active`	Present when active or pressed
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-state`	"checked" \| "unchecked"
`data-hover`	Present when hovered
`data-invalid`	Present when invalid
`data-orientation`	The orientation of the item
`data-ssr`	Present when not rendered in the browser. Useful for ssr styling

radioGroup.itemText

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

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

Rendered data attributes

Attribute	Description
`data-radio-group-item-text`	<uid>
`data-focus`	Present when focused
`data-focus-visible`	Present when focused with keyboard
`data-disabled`	Present when disabled
`data-readonly`	Present when read-only
`data-state`	"checked" \| "unchecked"
`data-hover`	Present when hovered
`data-invalid`	Present when invalid
`data-orientation`	The orientation of the item
`data-ssr`	Present when not rendered in the browser. Useful for ssr styling

radioGroup.indicator

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

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

Rendered data attributes

Attribute	Description
`data-radio-group-indicator`	<uid>
`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
`getRootState`	`() => RootState`	Returns the state of the radio group

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.

Radio Group

Features

Anatomy

Installation

Examples

Disabled Items

Disabled Group

No Default Value

API Reference

radioGroup.root

Rendered data attributes

radioGroup.label

Rendered data attributes

radioGroup.item

Rendered data attributes

radioGroup.itemHiddenInput

radioGroup.itemControl

Rendered data attributes

radioGroup.itemText

Rendered data attributes

radioGroup.indicator

Rendered data attributes

Machine JavaScript API

Accessibility

On this page