OptionCardGroup

Importing

In a React app, the component can be imported via:

import { OptionCardGroup } from '@customerio/pluma-components/react';

In an Ember app, the component is named PlumaOptionCardGroup.

Usage

An OptionCardGroup should contain OptionCard components as children. OptionCardGroup will forward the name attribute to any Checkboxes nested within, as well as connect onChange handlers to them, so there's no need to define those props on the OptionCards themselves:

Or, in Ember:

Labels

An OptionCardGroup must always have an associated label. The component accepts a label string prop, which renders text above the nested checkboxes.

Alternatively, ariaLabelledby may be used to associate the group with a label elsewhere in the DOM. To make sure the association is set up both ways, it's recommended to also set for on the label, pointing to an id on the checkbox group:

Finally, the ariaLabel prop can be used if no other element is suitable for a label.

Disabled groups

The isDisabled prop on an OptionCardGroup will take precedence over the isDisabled prop on individual OptionCard components.

It is not necessary to set isDisabled on the individual OptionCard components, as the OptionCardGroup provides that state to the cards through its context.

Input type

An inputType can be set o the OptionCardGroup, which will be passed down into the nested OptionCards:

Preventing selection

Just like in the OptionCard component, selection can be prevented with the canSelect prop. Note that deselecting is still allowed.

This is useful in cases where you need to limit a checkbox-based selection to a maximum number of options.

Size

The Option Card Group component accepts a size prop that controls the size of all option cards within the group. This allows you to easily set a consistent size for all cards in the group without having to specify it on each individual card.

The size property accepts either "md" (default) or "sm" as values.

Layout

By default, the cards will render in a flex container, with a gap of 200 and no wrapping. The layout of the card container can be customized through the following properties:

• shouldWrapCards
• cardsGap
• cardsColumnGap
• cardsRowGap
• cardsDirection
• cardsJustifyContent
• cardsAlignItems
• cardsAlignContent

For example:

Grid layout

Wrapping cards in a flex container gives every row as many cards as happen to fit, which leaves ragged rows and cards of differing widths. Set cardsLayout to grid to lay the cards out on a real grid instead. The card container then accepts the same grid configuration the Grid component does, through the cardsColumns, cardsRows, cardsAreas and cardsAutoFlow props:

cardsColumns accepts a number of equal-width columns, or any grid-template-columns value — for example "repeat(auto-fit, minmax(200px, 1fr))" for a responsive grid, or "2fr 1fr" for uneven columns.

Not every container prop applies to both layouts:

Keep the cards in the order you want them read. cardsAutoFlow values of column and dense, and explicit placement through cardsAreas, position cards in an order that no longer matches the DOM — but tab order and radio arrow-key navigation still follow the DOM, which is a WCAG 1.3.2 / 2.4.3 failure. Reorder the cards themselves rather than using auto-placement to reposition them.