Skip to content
Nexus Application Design nadesign

RadioCardGroup

<RadioCardGroup> is a Radix RadioGroup styled as cards. Use for onboarding / setup pickers where each option deserves a title + description block. For text-only radios, prefer RadioGroup.

import from "@na/ui/components/RadioCardGroup" ▶ Open in Storybook packages/ui/src/components/RadioCardGroup.tsx

When to use

  • Pricing / plan pickers in onboarding.
  • Setup steps where each option warrants explanation (“Lite”, “Standard”, “Enterprise”).
  • Any RadioGroup where the option text alone doesn’t carry the meaning.

Don’t use RadioCardGroup for: simple yes/no/maybe-style choices (RadioGroup is lighter), 6+ options (Combobox), or where the choice doesn’t need its own card frame.

Plans picker

 
<RadioCardGroup value={value} onValueChange={setValue} columns={3}>
  <RadioCardItem value="lite" title="Lite" description="Up to 5 agents." />
  <RadioCardItem
    value="standard"
    title="Standard"
    description="Unlimited agents."
    badge={<Badge variant="secondary">Recommended</Badge>}
  />
  <RadioCardItem
    value="enterprise"
    title="Enterprise"
    description="SSO, dedicated infra."
    disabled
  />
</RadioCardGroup>

API

RadioCardGroup

Prop Type Default Description
value string — Controlled value. Pair with onValueChange.
defaultValue string — Initial value for uncontrolled mode.
onValueChange (value: string) => void — Fires on every change.
columns 1 | 2 | 3 2 Cards-per-row at md and up. Mobile is always single-column.
disabled boolean false Disable every option.

RadioCardItem

Prop Type Default Description
value * string — Unique value within the group.
title * ReactNode — Card title — bold at the top.
description ReactNode — Optional muted description.
icon ReactNode — Optional leading icon.
badge ReactNode — Optional badge (recommendation, beta tag) right of the title.
disabled boolean false Skip during keyboard nav and click.

Design guidelines

✓ Do

  • Pre-select the most-likely option. The UX cost of forcing a click for the obvious choice is friction.
  • Use a "Recommended" badge sparingly — one option, max.
  • Keep titles short (1–2 words) and descriptions one short sentence.

✗ Don't

  • Render icons that don't add meaning. Decorative-only icons are noise.
  • Use RadioCardGroup for > 5 options. The card grid stops scanning well past that.

Accessibility

  • Composes Radix RadioGroup — role="radiogroup", items as role="radio".
  • Keyboard: arrow keys move between cards, Space selects.
  • The selected indicator (filled circle) is aria-hidden; the radio data-state carries the meaning.

▶ Open RadioCardGroup stories in Storybook