OptionCard

Usage

• Use OptionCard for visually prominent selection choices that benefit from icons and descriptions — plan selection, template picking, provider choosing.
• Use Radio or Checkbox instead when form choices need to be inline and visually subtle.
• OptionCard supports both single-select (radio) and multi-select (checkbox) modes via OptionCardGroup.
• Wrap OptionCards in an OptionCardGroup to manage shared state, selection mode, and layout.

Appearance

• Sizes: size="md" (default) provides more breathing room for titles and descriptions. size="sm" fits tighter layouts or simpler choices.
• Layouts: layout="horizontal" (default) left-aligns content; when an icon is present, it appears left of the content with a divider. layout="vertical" center-aligns content; icon appears above.
• Icons: Use icon for a Pluma icon name. Use iconSrc for a custom image URL (brand logos, illustrations). The image is decorative — meaning comes from the title or ariaLabel.
• Use vertical layout for icon-focused selections where the icon is the primary visual identifier.
• Use horizontal layout for text-heavy options with descriptions.

Behaviors

• Selection types: Set inputType="radio" (default) on OptionCardGroup for single-select — cards cannot be deselected. Set inputType="checkbox" for multi-select — each card toggles independently.
• Disabled state (isDisabled): Muted border and text, no interaction allowed.
• Can-select (canSelect): Prevents selection of unselected cards but still allows deselection of currently selected cards. Unlike isDisabled, does not fully lock the card.
• States: Supports base, hover, focus (standard 2px focus ring), and disabled states for both selected and unselected cards.

Content

• Keep titles to one to three words. Use sentence case with no end punctuation.
• Write titles that clearly name the option — avoid vague labels like "Option 1".
• Descriptions provide context the title alone cannot convey. Keep to a single short sentence explaining the option's purpose or behavior. End punctuation is not required.
• Never restate the title in the description without adding new information.
• Keep content structure consistent across all cards in a group — if one card has a title and description, all cards in the group must.

Implementation Notes

• Subcomponents: OptionCardTitle and OptionCardDescription are available for custom content composition. Use them inside children (React) or default block (Ember) when combining with additional elements like badges.
• Built-in vs custom content: The title and description props render built-in title/description. Pass children (React) or {{yield}} (Ember) for custom layouts — both built-in and custom content render together.
• Group composition: Always wrap OptionCards in OptionCardGroup. The group manages inputType, value, onChange, size, name, isDisabled, and canSelect via context — individual cards inherit these.
• Group value: For radio mode, value is a string. For checkbox mode, value is a string[]. The onChange callback signature matches accordingly.
• Group layout: Control card arrangement with cardsDirection (default "row"), cardsGap (default "200"), and shouldWrapCards on OptionCardGroup.
• onChange is deprecated on individual OptionCards — use onCheckedChange instead. On OptionCardGroup, onChange is the primary callback.
• Ember: Use <PlumaOptionCard> and <PlumaOptionCardGroup>. Args use @ prefix (@title, @icon, @layout). Custom content uses the default block ({{yield}}).