Choicebox

Choiceboxes are a great way to show radio or checkbox options with a card style.

Note: This component is deprecated and will no longer be maintained. Use Field component instead.

Loading component...

Installation

Usage

The Choicebox component provides a card-style radio group that makes options more visually prominent and easier to understand at a glance.

import {
  Choicebox,
  ChoiceboxItem,
  ChoiceboxItemHeader,
  ChoiceboxItemTitle,
  ChoiceboxItemSubtitle,
  ChoiceboxItemDescription,
  ChoiceboxItemContent,
  ChoiceboxItemIndicator,
} from "@/components/redpanda-ui/choicebox"

// Basic choicebox
<Choicebox defaultValue="option1">
  <ChoiceboxItem value="option1">
    <ChoiceboxItemHeader>
      <ChoiceboxItemTitle>Option 1</ChoiceboxItemTitle>
      <ChoiceboxItemDescription>
        This is the first option with a description
      </ChoiceboxItemDescription>
    </ChoiceboxItemHeader>
    <ChoiceboxItemContent>
      <ChoiceboxItemIndicator />
    </ChoiceboxItemContent>
  </ChoiceboxItem>
  <ChoiceboxItem value="option2">
    <ChoiceboxItemHeader>
      <ChoiceboxItemTitle>Option 2</ChoiceboxItemTitle>
      <ChoiceboxItemDescription>
        This is the second option
      </ChoiceboxItemDescription>
    </ChoiceboxItemHeader>
    <ChoiceboxItemContent>
      <ChoiceboxItemIndicator />
    </ChoiceboxItemContent>
  </ChoiceboxItem>
</Choicebox>

// With subtitles and controlled state
const [value, setValue] = useState("premium")

<Choicebox value={value} onValueChange={setValue}>
  <ChoiceboxItem value="basic">
    <ChoiceboxItemHeader>
      <ChoiceboxItemTitle>
        Basic Plan
        <ChoiceboxItemSubtitle>$9/month</ChoiceboxItemSubtitle>
      </ChoiceboxItemTitle>
      <ChoiceboxItemDescription>
        Perfect for getting started with basic features
      </ChoiceboxItemDescription>
    </ChoiceboxItemHeader>
    <ChoiceboxItemContent>
      <ChoiceboxItemIndicator />
    </ChoiceboxItemContent>
  </ChoiceboxItem>
  <ChoiceboxItem value="premium">
    <ChoiceboxItemHeader>
      <ChoiceboxItemTitle>
        Premium Plan
        <ChoiceboxItemSubtitle>$29/month</ChoiceboxItemSubtitle>
      </ChoiceboxItemTitle>
      <ChoiceboxItemDescription>
        Full access to all features and priority support
      </ChoiceboxItemDescription>
    </ChoiceboxItemHeader>
    <ChoiceboxItemContent>
      <ChoiceboxItemIndicator />
    </ChoiceboxItemContent>
  </ChoiceboxItem>
</Choicebox>

When to use

Use this decision tree to determine when to use the Choicebox component:

Use Choicebox when:

Options require detailed descriptions or explanations
Visual hierarchy and prominence are important
Presenting pricing plans, feature tiers, or service levels
Users need to compare options side-by-side
Each option has multiple pieces of information (title, subtitle, description)
Building settings panels where options need context
Creating forms where visual appeal enhances user experience

Don't use Choicebox for:

Simple yes/no choices (use Radio Group or Switch)
Multiple selections (use Checkbox or Multi-Select)
Long lists of options (use Select or Combobox)
Navigation choices (use Tabs or Navigation Menu)
When space is extremely limited

Anatomy

The Choicebox component builds on Radio Group with enhanced card-style presentation:

Choicebox Component Structure:
┌─────────────────────────────────────────────────────────────┐
│ <Choicebox> (RadioGroup wrapper)                           │
│                                                             │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ <ChoiceboxItem> (RadioGroupPrimitive.Item + Card)      │ │
│ │                                                         │ │
│ │ Layout: Flex Row (justify-between)                     │ │
│ │ ┌─────────────────────────────┐ ┌─────────────────────┐ │ │
│ │ │ <ChoiceboxItemHeader>       │ │ <ChoiceboxItemContent>│ │ │
│ │ │ (CardHeader - flex-1)       │ │ (Radio indicator)     │ │ │
│ │ │                             │ │                       │ │ │
│ │ │ ┌─────────────────────────┐ │ │ ┌─────────────────────┐ │ │
│ │ │ │ <ChoiceboxItemTitle>    │ │ │ │ Circle container    │ │ │
│ │ │ │ (CardTitle + flex gap)  │ │ │ │ (4x4, rounded-full) │ │ │
│ │ │ │                         │ │ │ │                     │ │ │
│ │ │ │ ┌─────────────────────┐ │ │ │ │ ┌─────────────────┐ │ │ │
│ │ │ │ │ Title Text          │ │ │ │ │ │<ChoiceboxItem  │ │ │ │
│ │ │ │ └─────────────────────┘ │ │ │ │ │Indicator>      │ │ │ │
│ │ │ │ ┌─────────────────────┐ │ │ │ │ │                 │ │ │ │
│ │ │ │ │<ChoiceboxItemSub    │ │ │ │ │ │<motion.div>    │ │ │ │
│ │ │ │ │title> (Optional)    │ │ │ │ │ │<Circle> (filled)│ │ │ │
│ │ │ │ └─────────────────────┘ │ │ │ │ │                 │ │ │ │
│ │ │ └─────────────────────────┘ │ │ │ └─────────────────┘ │ │ │
│ │ │ ┌─────────────────────────┐ │ │ └─────────────────────┘ │ │
│ │ │ │<ChoiceboxItemDescription│ │ │                         │ │
│ │ │ │> (CardDescription)      │ │ │                         │ │
│ │ │ └─────────────────────────┘ │ │                         │ │
│ │ └─────────────────────────────┘ └─────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────┐ │
│ ┌─────────────────────────────────────────────────────────┐ │
│ │ <ChoiceboxItem> (Additional items...)                  │ │
│ │ ... (Same structure as above)                          │ │
│ └─────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘

Component Hierarchy:
• Choicebox (RadioGroup): Manages selection state
• ChoiceboxItem (Card + RadioItem): Individual option container
• ChoiceboxItemHeader (CardHeader): Content area (titles, descriptions)
• ChoiceboxItemTitle (CardTitle): Main option name
• ChoiceboxItemSubtitle (span): Secondary text (price, status, etc.)
• ChoiceboxItemDescription (CardDescription): Detailed explanation
• ChoiceboxItemContent (CardContent): Radio indicator container
• ChoiceboxItemIndicator: Animated selection indicator

State Management:
• Built on Radix Radio Group primitives
• Supports controlled (value/onValueChange) and uncontrolled (defaultValue)
• Selection state automatically managed across all items
• Focus and keyboard navigation handled automatically

Visual States:
• Default: Neutral border and background
• Hover: Selected color border at 50% opacity
• Selected: Selected color border, selected background tint (5% opacity)
• Disabled: Reduced opacity, no interactions
• Focus: Ring outline for accessibility

Animation Features:
• Motion library integration for indicator
• Spring animation on selection (scale from 0 to 1)
• Smooth color transitions on state changes
• Customizable transition timing via props

Features

Card-style radio and checkbox options
Customizable header, title, and description for each option
Accessible keyboard navigation
Visual feedback for selected and hover states
Support for disabled states
Customizable styling through className props
Flexible layout with inline and block options
Clear visual hierarchy with title and subtitle support
Consistent styling with the design system
Support for custom content and indicators

Examples

Inline Choiceboxes

Open in

Loading component...

Form

Open in

Loading component...

Props

Docs API Reference

Credits

We use Kibo UI for the choice box component and style.

Installation

Usage

When to use

Anatomy

Features

Examples

Inline Choiceboxes

Form

Props

Credits

On this page