RadioGroup

RadioGroup coordinates the value, keyboard navigation, and form submission of its Radio children.

Usage

Uncontrolled state

Use defaultValue to set the initial billing frequency. The group owns subsequent changes.

import { Radio, RadioGroup } from 'twenty-ui/primitives/input';

export const BillingFrequency = () => (
  <RadioGroup
    name="billingFrequency"
    defaultValue="monthly"
    aria-label="Billing frequency"
  >
    <Radio value="monthly">Monthly</Radio>
    <Radio value="yearly">Yearly</Radio>
  </RadioGroup>
);

The group’s name identifies the selected value in form submission. Give the group an accessible name as well as labeling each radio.

Anatomy

Put each Radio or Radio.Root inside the group and associate it with a label. Use Radio.Indicator to compose a custom indicator. RadioGroup and Radio are separate exports.

fieldset
├── legend
└── RadioGroup
    ├── label
    │   └── Radio
    └── label
        └── Radio

Part	Requirement	Purpose
`RadioGroup`	Required	Owns selection, keyboard navigation, and form integration.
`Radio`	One per option	Supplies an option with a distinct `value`.
`label`	Recommended for each option	Provides a visible, clickable name for its radio.
`fieldset`, `legend`	Optional grouping	Groups related controls under a visible heading.

Give the group its own accessible name using aria-label or aria-labelledby. In the examples below, aria-labelledby connects the group to the legend. Each radio also needs its own name. Put selection props on RadioGroup and option values on Radio.

Controlled state

Pass value and update it with onValueChange to own the same billing frequency in React state. Selection belongs to the group, not to individual radio controls.

import { useId, useState } from 'react';
import { Radio, RadioGroup } from 'twenty-ui/primitives/input';

export const BillingFrequency = () => {
  const labelId = useId();
  const [billingFrequency, setBillingFrequency] = useState('monthly');

  return (
    <fieldset>
      <legend id={labelId}>Billing frequency</legend>
      <RadioGroup
        name="billingFrequency"
        value={billingFrequency}
        onValueChange={setBillingFrequency}
        aria-labelledby={labelId}
      >
        <label>
          <Radio value="monthly" />
          Monthly
        </label>
        <label>
          <Radio value="yearly" />
          Yearly
        </label>
      </RadioGroup>
    </fieldset>
  );
};

onValueChange receives the next value and event details. The generic value type is inferred from the props. Use disabled on the group to disable every option, or on an individual radio to disable one choice. Arrow keys navigate and select enabled options; Tab moves out of the group. The installed Base UI version supports both horizontal and vertical arrow keys and does not expose an orientation prop. Use DirectionProvider for right-to-left horizontal navigation. Visual row or column layout does not replace the upstream keyboard behavior.

Native integration and event details

RadioGroup renders a div by default. Native props and ref target that element; render composes another element and changes the actual ref target. inputRef targets the representative hidden input of a child radio, using the selected enabled option or an enabled fallback. The public types include generic RadioGroupProps, RadioGroupState, RadioGroupChangeEventReason and RadioGroupChangeEventDetails. The callback receives the original event details, including the native event, reason, cancel() and allowPropagation(). Cancel a proposed change before updating controlled state when the choice should be rejected. Keep name, form, required, disabled and readOnly on the group for the existing Base UI form contract. The selected value is submitted under name; disabled groups are excluded and read-only groups keep their selection. form supports a group outside its owning form. The installed version does not restore group state automatically on native form reset. Reset controlled state from the form’s onReset handler when your workflow requires it. In sandboxed front components, put the group inside its owning form. The renderer forwards required validation and blocks explicit form references, which otherwise resolve across the host document. SegmentedControl is a convenience preset assembled from these primitives for a short exclusive choice. It uses radio semantics and requires an accessible group name. Tabs and tab-panel navigation are separate controls.

Props

The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.

string | ((state: RadioGroupState) => string | undefined)

CSS class applied to the element, or a function that returns a class based on the component’s state.

TValue

The uncontrolled value of the radio button that should be initially selected.To render a controlled radio group, use the value prop instead.

boolean

default:"false"

Whether the component should ignore user interaction.

string

Identifies the form that owns the radio inputs. Useful when the radio group is rendered outside the form.

Ref<HTMLInputElement>

A ref to access the hidden input element.

string

Identifies the field when a form is submitted.

((value: TValue, eventDetails: { reason: "none"; event: Event; cancel: () => void; allowPropagation: () => void; isCanceled: boolean; isPropagationAllowed: boolean; trigger: Element | undefined; }) => void)

Callback fired when the value changes.

boolean

default:"false"

Whether the user should be unable to select a different radio button in the group.

ReactElement<unknown, string | JSXElementConstructor<any>> | ComponentRenderFn<HTMLProps, RadioGroupState>

Allows you to replace the component’s HTML element with a different tag, or compose it with another component.Accepts a ReactElement or a function that returns the element to render.

boolean

default:"false"

Whether the user must choose a value before submitting a form.

CSSProperties | ((state: RadioGroupState) => CSSProperties | undefined)

Style applied to the element, or a function that returns a style object based on the component’s state.

TValue

The controlled value of the radio item that should be currently selected.To render an uncontrolled radio group, use the defaultValue prop instead.

Overview

Apps

API

Self-Host

Contribute

UI Library

Usage

Uncontrolled state

Anatomy

Controlled state

Native integration and event details

Props

​Usage

​Uncontrolled state

​Anatomy

​Controlled state

​Native integration and event details

​Props

Usage

Uncontrolled state

Anatomy

Controlled state

Native integration and event details

Props