Radio

A group of options where only one can be selected.

FreeProTeam

Usage

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

<RadioGroup defaultValue="pro" aria-label="Plan">
  <label className="flex items-center gap-2">
    <Radio value="free" />
    Free
  </label>
  <label className="flex items-center gap-2">
    <Radio value="pro" />
    Pro
  </label>
  <label className="flex items-center gap-2">
    <Radio value="team" />
    Team
  </label>
</RadioGroup>

A Radio never stands alone - it only works inside a RadioGroup, which owns the selected value and the roving focus that lets arrow keys move between options. Each radio is identified by its value; that's what selection reports back. Wrap each radio and its text in a <label> so the text is clickable and announced together. The fill/squish animation is skipped when the user prefers reduced motion.

Examples

Default

Set the initial selection with defaultValue (uncontrolled) on the group, or drive it yourself with value + onValueChange. The group lays its options out in a column by default.

PlanFreeProTeam

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const plans = [
  { value: 'free', label: 'Free' },
  { value: 'pro', label: 'Pro' },
  { value: 'team', label: 'Team' },
]

export default function RadioGroupExample() {
  return (
    <RadioGroup defaultValue="pro" aria-labelledby="plan-label">
      <span id="plan-label" className="text-foreground mb-1 text-sm font-medium">
        Plan
      </span>
      {plans.map((plan) => (
        <label key={plan.value} className="flex items-center gap-2 text-sm select-none">
          <Radio value={plan.value} />
          {plan.label}
        </label>
      ))}
    </RadioGroup>
  )
}

Horizontal

Pass orientation="horizontal" to lay the options out in a row. This also switches the arrow keys that move selection from ↑/↓ to ←/→.

SmallMediumLarge

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const sizes = [
  { value: 's', label: 'Small' },
  { value: 'm', label: 'Medium' },
  { value: 'l', label: 'Large' },
]

export default function RadioGroupOrientation() {
  return (
    <RadioGroup orientation="horizontal" defaultValue="m" aria-label="Size">
      {sizes.map((size) => (
        <label key={size.value} className="flex items-center gap-2 text-sm select-none">
          <Radio value={size.value} />
          {size.label}
        </label>
      ))}
    </RadioGroup>
  )
}

Sizing

Radio is sized in em, so it scales with the surrounding font size - set a text-* class on the wrapping <label> and the control and text grow together. It won't shrink below a 16px floor.

text-basetext-lgtext-xl

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

export default function RadioSizing() {
  return (
    <RadioGroup defaultValue="base" aria-label="Size" className="items-start gap-4 select-none">
      <label className="flex items-center gap-2 text-base">
        <Radio value="base" />
        text-base
      </label>
      <label className="flex items-center gap-2.5 text-lg">
        <Radio value="lg" />
        text-lg
      </label>
      <label className="flex items-center gap-3 text-xl">
        <Radio value="xl" />
        text-xl
      </label>
    </RadioGroup>
  )
}

Disabled

Disable the whole set with disabled on the RadioGroup, or a single option with disabled on its Radio. A disabled option is skipped by arrow-key navigation.

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

export default function RadioGroupDisabled() {
  return (
    <div className="flex flex-col gap-8">
      <RadioGroup defaultValue="standard" aria-label="Shipping">
        <label className="flex items-center gap-2 text-sm select-none">
          <Radio value="standard" />
          Standard
        </label>
        <label className="flex items-center gap-2 text-sm select-none">
          <Radio value="express" />
          Express
        </label>
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="overnight" disabled />
          Overnight (unavailable)
        </label>
      </RadioGroup>

      <RadioGroup defaultValue="yearly" disabled aria-label="Billing period">
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="monthly" />
          Monthly
        </label>
        <label className="text-foreground-muted flex items-center gap-2 text-sm select-none">
          <Radio value="yearly" />
          Yearly
        </label>
      </RadioGroup>
    </div>
  )
}

With descriptions

Pair each option's label with supporting text, aligning the radio to the first line. Keeping it all inside the <label> makes the whole row one target.

PublicAnyone on the internet can see this project.PrivateOnly you and people you invite can access it.TeamEveryone in your organization can view and edit.

import { RadioGroup } from '@appica/ui-react/radio-group'
import { Radio } from '@appica/ui-react/radio'

const visibilities = [
  { value: 'public', label: 'Public', description: 'Anyone on the internet can see this project.' },
  { value: 'private', label: 'Private', description: 'Only you and people you invite can access it.' },
  { value: 'team', label: 'Team', description: 'Everyone in your organization can view and edit.' },
]

export default function RadioGroupWithDescriptions() {
  return (
    <RadioGroup defaultValue="private" aria-label="Visibility" className="max-w-md">
      {visibilities.map((visibility) => (
        <label key={visibility.value} className="flex items-start gap-2.5 select-none">
          <Radio value={visibility.value} className="mt-1" />
          <span className="flex flex-col">
            <span className="text-foreground-intense font-medium">{visibility.label}</span>
            <span className="text-foreground-muted text-sm">{visibility.description}</span>
          </span>
        </label>
      ))}
    </RadioGroup>
  )
}

RTL

Every Appica UI component supports right-to-left layouts out of the box. Set the dir attribute on a container (commonly your <html> element) so CSS logical properties resolve correctly, and wrap your tree in DirectionProvider so direction-aware behavior (roving focus, popup placement, and the like) follows the same direction.

import { DirectionProvider } from '@appica/ui-react/providers/direction-provider'

export default function RootLayout({ children }) {
  return (
    <html lang="ar" dir="rtl">
      <body>
        <DirectionProvider dir="rtl">{children}</DirectionProvider>
      </body>
    </html>
  )
}

For setup details and caveats, see the RTL guide.

اختر الخطةمجانياحترافيفريق

API reference

RadioGroup and Radio wrap Base UI's Radio. The group renders a <div role="radiogroup"> and each Radio a role="radio"; both forward ref, aria-*, and their native attributes, and expose data-* state attributes (data-checked, data-unchecked, data-disabled, data-readonly, …) for styling. See the Base UI docs for the complete API.

RadioGroup

The container that owns the selected value and keyboard navigation.

Prop	Type	Default	Description
`value`	`string`	-	Controlled selected value. Pair with `onValueChange`.
`defaultValue`	`string`	-	Uncontrolled initial selection.
`onValueChange`	`(value: string, details) => void`	-	Fires when the selection changes.
`orientation`	`'horizontal' \| 'vertical'`	`'vertical'`	Lay options out in a row or column; sets which arrow keys move selection.
`name`	`string`	-	Field name submitted with a form.
`disabled`	`boolean`	`false`	Disables every radio in the group.
`readOnly`	`boolean`	`false`	Focusable, but the selection can't be changed.
`required`	`boolean`	`false`	An option must be chosen before the form submits.
`inputRef`	`Ref`	-	Ref to the hidden input element.
`render`	`ReactElement \| ((props, state) => ReactElement)`	-	Replace the group element, or compose it with another component.
`className`	`string \| ((state) => string)`	-	Extra classes, merged via `tailwind-merge` (override the default `flex` layout here).
`style`	`CSSProperties \| ((state) => CSSProperties)`	-	Inline styles, optionally derived from state.

Radio

One option inside a RadioGroup.

Prop	Type	Default	Description
`value`	`string`	-	Required. The value this option selects; reported by the group on change.
`disabled`	`boolean`	`false`	Removes this option from the tab order and skips it during arrow navigation.
`readOnly`	`boolean`	`false`	Focusable but not selectable.
`required`	`boolean`	`false`	Marks this option required for form submission.
`nativeButton`	`boolean`	`false`	Whether the element passed to `render` is a native `<button>`.
`inputRef`	`Ref<HTMLInputElement>`	-	Ref to the hidden `<input>` element backing the radio.
`id`	`string`	-	`id` of the rendered element.
`render`	`ReactElement \| ((props, state) => ReactElement)`	-	Replace the rendered element, or compose it with another component.
`className`	`string \| ((state) => string)`	-	Extra classes on the radio, merged via `tailwind-merge`. May be a function of state.
`style`	`CSSProperties \| ((state) => CSSProperties)`	-	Inline styles, optionally derived from state.

Accessibility

RadioGroup renders a <div role="radiogroup"> and each Radio a role="radio". Name the group with aria-label or aria-labelledby.
The group is a single tab stop: Tab moves focus into the selected option (or the first one), and the arrow keys move the selection between options (↑/↓ when vertical, ←/→ when horizontal) wrapping around the ends.
Each radio needs an accessible name - wrap it in a <label> together with its text, or give it an aria-label.
disabled on a radio or the group removes the affected options from the tab order and exposes data-disabled for styling; disabled options are skipped during arrow navigation.
The fill/squish animation honors prefers-reduced-motion.

Actions & Inputs

Data Display

Decoration & Effects

Layout

Menus

Navigation

Overlays

Status & Feedback

Radio

Usage

Examples

Default

Horizontal

Sizing

Disabled

With descriptions

RTL

API reference

RadioGroup

Radio

Accessibility