Skip to content

Radio Group

Get Ritla UI

For choosing exactly one option from a short list that's all in view; picking one clears the others. The circle sits at the inline start.

Ritla scan of this preview: 41 of 41 checks3 breakpointsScanned

Open in Figma

Preview

Mirrored is the same English content laid out right to left: it separates a mirroring bug from a translation one.

PreviewCode
EnglishMirroredArabic
LTR →

Installation

  1. Add the component

    npx ritla add radio

    Also works with shadcn: npx shadcn@latest add @ritla/radio

  2. Dependencies it brings

    @base-ui/react

  3. Or copy by hand

    Installing by hand copies the component's source into your project. The source comes with a Ritla UI license, so the CLI is the short way to the same files.

Usage

radio.tsx
import { Radio, RadioGroup } from "@/components/ui/radio";<RadioGroup label="Delivery" name="delivery" defaultValue="standard">  <Radio value="standard">Standard</Radio>  <Radio value="express">Express</Radio></RadioGroup>

Examples

States and size

error marks every circle, disabled and readOnly apply to the whole group, and size="lg" is the large touch circle with its halo.

EnglishMirroredArabic
LTR →

API reference

RadioGroup

PropTypeDefaultDescription
labelReactNodeNoneFigma's Label: the group's name.
value / defaultValuestring | nullNoneThe chosen option.
onValueChange(value: string) => voidNoneWhen an option is picked.
namestringNoneForm field name.
required / helperText / error / disabled / readOnly…NoneAs on Input Field; an error marks every circle.

Radio

PropTypeDefaultDescription
valuestringNoneThe option's value. Required.
childrenReactNodeNoneFigma's Label: the option's text.
descriptionReactNodeNoneA helper line.
size"sm" | "lg""sm"Small (Web) or Large (Native).
disabled / readOnlybooleanNoneFor one option.

Usage guidelines

Radios are for a single choice from a short list people should see in full. When to pick them, what the default is, how to order and word the options, and the checks before handoff.

1. Radios or another control

Radios fit a single choice from a short list people should see in full. They take space, which is the point: every option is visible and comparable. When the list is long, the change applies at once, or the question is a yes or no, another control fits better.

You need toUseWhy
Pick one of 2 to 5 options in a formRadio groupEvery option is visible and one press away.
Pick one option that needs a description or a priceRadio button cardRoom for details; the whole card is the target.
Pick one of many optionsSelectA long list of radios is hard to scan.
Switch a view or filter at onceToggle groupIt applies immediately, without a submit.
Answer one yes or noCheckbox or SwitchA single radio can't be turned off again.

2. The default

Once a radio is selected, people can't clear it, only pick another. So choose the starting state on purpose. Preselect the safest or most common option when there is one, like standard delivery. When the answer is personal or needs a real decision, start with none selected and require one.

A safe default in a real group

Delivery options at checkout.

Do: Standard preselectedThe common, free choice is ready; Express is one press away.
Don't: A lone radioOnce selected, “Gift wrap” can't be turned off again; that is a checkbox.

Do

  • Preselect a safe, common default: Standard delivery, Monthly billing.
  • Leave personal questions empty and make them required.
  • Add a “None” or “Not now” option when skipping is a valid answer.

Don't

  • Preselect a paid upgrade or the most expensive plan.
  • Use a single radio button for a yes or no; it can't be unselected.
  • Change the default between visits without a reason.

3. Order and wording

List options in an order people expect: by size, time, price or frequency, and alphabetically only when nothing else applies. Keep labels short and parallel, and put details in the helper text. “Other” or “None” goes last.

Do

  • Order by a natural sequence: small to large, cheapest to most expensive.
  • Write parallel labels: all nouns, or all short phrases.
  • Put “Other” or “None” last.
  • Stack options vertically, one per line.

Don't

  • Mix a sentence with one-word options.
  • Lay radios out in a row when labels vary in length.
  • Hide a key difference, like a price, in a tooltip.

4. Radio button cards

A Radio button card is a list row or card chosen with a radio, for options that need more than a label: plans, shipping methods, saved cards. The whole card is the label. The radio sits at the inline end, or at the start with Leading type = Radio.

Do

  • Use cards for options people compare on several details.
  • Keep the headline to the option's name, the details in the supporting text, a price as trailing text.
  • Keep all cards in a group the same height and layout.

Don't

  • Mix radio cards and plain radios in one group.
  • Put buttons or links inside a card.

5. Arabic and RTL

On Arabic screens use the RTL variants: the circle sits at the inline start (the right) and labels run to its left. In code the arrow keys follow the reading order, so ArrowLeft moves to the next option in Arabic. The selected dot never mirrors.

The circle sits at the inline start

Delivery options in Arabic.

Do: RTL variantThe circles line up on the right, where the Arabic line starts.
Don't: English variant with Arabic textThe circles sit after the text, on the left.

Before handoff

  • Radios for 2 to 5 options, a select beyond that.
  • The default is decided: a safe option, or none and required.
  • Options are ordered and worded in parallel.
  • Arabic screens use RTL variants.

Accessibility

Keyboard

Keys are written for left-to-right. In right-to-left the arrow keys swap: the one pointing toward the reading direction moves forward.

KeyAction
TabEnters the group at the chosen (or first) option, and leaves it.
ArrowDownArrowRightNext option, and selects it. In Arabic, ArrowLeft is next.
ArrowUpArrowLeftPrevious option, and selects it.

ARIA

  • role="radiogroup" named by its label and linked to its helper or error; each option is role="radio" named by its text.
  • Don't act on selection; wait for submit.

Do

  • Label the group; the label is the question.
  • Tab enters on the selected option; arrows move and select.
  • The label is clickable; the whole row is the target.
  • The group's error sits under the last option.

Don't

  • Run an action or navigate on selection; wait for submit.
  • Rely on the dot alone; the label says what is selected.

Arabic and RTL notes

Mirrors

  • The circles sit at the inline start (the right), and the horizontal arrows follow the reading order.

Does not mirror

  • The dot is symmetric.
Numerals
No numbers in the circle.
Arabic typography
Options are label-16 Medium, descriptions label-12.

Do

  • The RTL variant for every radio in an Arabic form.
  • Write the options natively, with names and prices in their own script.

Don't

  • Arabic in the English variant.
  • Keep the English option order when it follows the reading direction, like a scale from left to right.

Checks it passes

The Ritla checks this component satisfies by construction. Used as documented, it does not bring these defects onto your page.

  • R050Arabic text falling back past the declared font family (measured, declared, or a webfont that failed to load)
  • R051letter-spacing applied to Arabic text (breaks the connected script)
  • R042Clipped text: content wider than its box with overflow hidden and no ellipsis
  • R043Fixed-pixel-width container whose Arabic text exceeds the space