OptionCard
'%3e%3cpath%20d='M19%2028.5C19%2025.9804%2020.0009%2023.5641%2021.7825%2021.7825C23.5641%2020.0009%2025.9804%2019%2028.5%2019C31.0196%2019%2033.4359%2020.0009%2035.2175%2021.7825C36.9991%2023.5641%2038%2025.9804%2038%2028.5C38%2031.0196%2036.9991%2033.4359%2035.2175%2035.2175C33.4359%2036.9991%2031.0196%2038%2028.5%2038C25.9804%2038%2023.5641%2036.9991%2021.7825%2035.2175C20.0009%2033.4359%2019%2031.0196%2019%2028.5Z'%20fill='%231ABCFE'/%3e%3cpath%20d='M0%2047.5C0%2044.9804%201.00089%2042.5641%202.78249%2040.7825C4.56408%2039.0009%206.98044%2038%209.5%2038H19V47.5C19%2050.0196%2017.9991%2052.4359%2016.2175%2054.2175C14.4359%2055.9991%2012.0196%2057%209.5%2057C6.98044%2057%204.56408%2055.9991%202.78249%2054.2175C1.00089%2052.4359%200%2050.0196%200%2047.5H0Z'%20fill='%230ACF83'/%3e%3cpath%20d='M19%200V19H28.5C31.0196%2019%2033.4359%2017.9991%2035.2175%2016.2175C36.9991%2014.4359%2038%2012.0196%2038%209.5C38%206.98044%2036.9991%204.56408%2035.2175%202.78249C33.4359%201.00089%2031.0196%200%2028.5%200L19%200Z'%20fill='%23FF7262'/%3e%3cpath%20d='M0%209.5C0%2012.0196%201.00089%2014.4359%202.78249%2016.2175C4.56408%2017.9991%206.98044%2019%209.5%2019H19V0H9.5C6.98044%200%204.56408%201.00089%202.78249%202.78249C1.00089%204.56408%200%206.98044%200%209.5H0Z'%20fill='%23F24E1E'/%3e%3cpath%20d='M0%2028.5C0%2031.0196%201.00089%2033.4359%202.78249%2035.2175C4.56408%2036.9991%206.98044%2038%209.5%2038H19V19H9.5C6.98044%2019%204.56408%2020.0009%202.78249%2021.7825C1.00089%2023.5641%200%2025.9804%200%2028.5H0Z'%20fill='%23A259FF'/%3e%3c/g%3e%3cdefs%3e%3cclipPath%20id='clip0_1_137'%3e%3crect%20width='38'%20height='57'%20fill='white'/%3e%3c/clipPath%3e%3c/defs%3e%3c/svg%3e){kind=small}
Figma
Github
StorybookOptionCards present the functionality of a radio or checkbox in a more visually prominent card format with an increased click area.
Anatomy
- Container: Wraps the hidden input and all visual content. Acts as the click target for selection.
- Icon (optional): A Pluma icon or custom image that visually represents the option.
- Divider (optional): A vertical separator between the icon and content areas. Only appears in horizontal layout when both an icon and a title are present.
- Title (optional): Heading text that labels the option.
- Description (optional): Provides additional context about the option.
Guidelines
OptionCard vs Checkbox and Radio
OptionCard, Checkbox, and Radio all let users make single or multiple selections to fill out a form. However, it's important to understand the difference as they are not interchangeable:
- OptionCards present choices as visually prominent cards with an increased click area. They are best used for decisions that benefit from icons and descriptions such as choosing a plan, selecting a template, or picking a provider.
- Radios are limited to only one choice in a group of options that cannot be deselected. Use them when form choices must be inline and more visually subtle.
- Checkboxes allow users to select zero or more options independently and allow for deselection. Use them when form choices must be inline and more visually subtle.
Best practices
Consistent content
When options appear together in a group, keep content structure consistent across all cards. If one card has a title and description, all cards should have titles and descriptions.
Layout direction
Use the default horizontal layout for most option groups, especially when description is important to the card. Vertical layout works best for icon-focused selections where the icon is the primary visual identifier and communication tool, such as choosing a provider or integration.
Customization
Custom content
OptionCard supports custom children alongside or instead of the built-in title and description. Use custom content to include additional elements like status indicators, badges, or structured layouts.
The title and description props cover most use cases.
Pass children to add elements beyond a title and description.
Custom images
If Pluma icons don't satisfy a use case, custom graphics can be used. The image will adhere to the same positioning and size rules as the standard icon.
Use the icon prop for standard icons from the Pluma icon library.
Use iconSrc for brand logos or illustrations not available in the icon library.
Appearance
Icons
OptionCard supports both Pluma icons and custom images. Icons help users quickly identify options visually, especially in groups.
In horizontal layout with a title, the icon appears to the left of the content, separated by a divider. In vertical layout, the icon appears above the content and the text is centered.
Use a Pluma icon name to display a standard icon from the icon library.
Use an image URL for brand logos or illustrations that don't exist in the icon library.
Layouts
The OptionCard can be displayed in either horizontal or vertical layouts. Determine which option is best depending on how much available space there is.
In the default horizontal layout, content is left-aligned. When an icon is present, it appears to the left of the content with a divider between them.
Content is center-aligned. When an icon is present, it appears above the content.
Sizes
The OptionCard is available in two sizes: medium and small.
Medium is the default, used in the majority of cases. Provides more breathing room for titles and descriptions.
Small is preferred for tighter layouts or simpler choices where less visual emphasis is required.
Behaviors
States
With no user interaction, the OptionCard shows default styles.
On mouse hover, the border color updates to indicate the card is interactive.
On keyboard focus, the card receives the standard 2px focus ring.
Disabled cards cannot be interacted with. The border and text colors are muted to indicate the card is unavailable.
Selection types
OptionCard supports two selection modes that change how the underlying input behaves:
-
Radio: This default mode allows only one card to be selected within a group. Similar to radios, cards may not be deselected. Another card must be chosen instead. Use this mode for cases where only one selection is required.
-
Checkbox: This mode allows multiple cards to be selected independently. Each card can be toggled on and off. Use checkbox mode when users should be able to select zero or more options.
Only one option can be selected at a time. Clicking a selected card does not deselect it.
Multiple options can be selected independently. Clicking a selected card deselects it.
Content
Assistive text
Description
Descriptions provide additional context to the card that cannot be conveyed by the title alone. Keep them to a single short sentence that explain the option's purpose or behavior. End punctuation is not required.
Titles
Write titles that clearly name the option being presented. Keep them to one to three words when possible. Use sentence case with no end punctuation.