Componentsv2.170.1

Iconsv1.15.0

MCPv0.8.18

Tokensv0.34.1

OptionCard

Figma

Github

Storybook

Aria pattern Legacy component

A radio or checkbox input wrapped in a card. It can be used anywhere you would use radio or checkbox inputs, where users are asked to make a choice from a number of options. The OptionCard, however, renders a more visually prominent card, with an increased click area, compared to a standard radio or checkbox.

Usually this component should be used with the OptionCardGroup component.

Importing

The component can be imported via:

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

Usage

When using a standalone OptionCard, at a minimum you will need to supply:

an isSelected state
a handler for state changes (either onCheckedChange or onChange)
a title
an inputType (this defaults to radio)

You can also customize the option card with:

a size of sm or md (defaults to md)
a layout of horizontal or vertical (when using with an icon)
an icon property for visual context

Default card

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

export default function Example() {
	const [selected, setSelected] = useState(false);

	return <OptionCard
		value="card_value"
		title="Default card"
		inputType="checkbox"
		isSelected={selected}
		onCheckedChange={(checked) => {
			setSelected(checked);
		}}
	/>
}

More examples of available props:

Enabled card

Deselected card

Disabled card

Description-only card

<Box 
	display="flex"
	flexDirection="column" 
	alignItems="flex-start"
	gap="200"
>
	<OptionCard
		value="enabled_card"
		title="Enabled card"
		isSelected={true}
		onCheckedChange={() => {}}
	/>

	<OptionCard
		value="deselected_card"
		title="Deselected card"
		isSelected={false}
		onCheckedChange={() => {}}
	/>

	<OptionCard
		value="disabled_card"
		title="Disabled card"
		isSelected={false}
		isDisabled={true}
		onCheckedChange={() => {}}
	/>

	<OptionCard
		value="description_card"
		description="Description-only card"
		onCheckedChange={() => {}}
	/>
</Box>

Titles and descriptions

An OptionCard must always include a title and/or description. The content will render inside the card, and there is no distinction between a "label" and a "description", from an accessibility point of view, due to the card's layout (the whole card is a <label> tag).

Titles and descriptions can be provided via the title and description props:

No conversionDon't track conversions

<OptionCard
	value="no_conversion"
	title="No conversion"
	description="Don't track conversions"
/>

Icons

An icon can be rendered inside the card to provide additional visual context. This can be done with the icon prop, which accepts a Pluma Icon name.

Segment-triggered

<OptionCard
	value="segment"
	title="Segment-triggered"
	icon="segment"
/>

Segment-triggeredTrigger when entering or leaving a segment

<OptionCard
	value="segment"
	title="Segment-triggered"
	description="Trigger when entering or leaving a segment"
	icon="segment"
/>

Email attribute

<OptionCard
	value="email"
	description="Email attribute"
	icon="email"
/>

Layout

When an icon is present, OptionCard can be rendered in a horizontal or vertical layout, which can be changed via the layout prop:

Segment-triggered

<Box 
	display="flex"
	gap="200"
>
	<OptionCard
		value="segment"
		title="Segment-triggered"
		icon="segment"
		layout="horizontal"
	/>

	<OptionCard
		value="segment"
		title="Segment-triggered"
		icon="segment"
		layout="vertical"
	/>
</Box>

Size

OptionCard can be rendered in two sizes: sm (small) and md (medium, default). The size can be changed via the size prop:

Small sizeCompact option

Medium sizeDefault option

<Box 
	display="flex"
	gap="200"
>
	<OptionCard
		value="small"
		title="Small size"
		description="Compact option"
		size="sm"
	/>

	<OptionCard
		value="medium"
		title="Medium size"
		description="Default option"
		size="md"
	/>
</Box>

Custom content

If you need to render custom content in a card (when string title and description props aren't enough), you can the content into the OptionCard component in block form:

Custom content

Visit our docs.

<OptionCard
	value="test_value"
>
	<Box backgroundColor="accent-subtle">
		<Text as="p">Custom content</Text>
		<Text as="p">
			Visit our <Link href="https://customer.io/docs" isExternal={true}>docs</Link>.
		</Text>
	</Box>
</OptionCard>

You may also use the card's title and description components, if you want to render custom content but still use the card's styles.

import { OptionCardTitle, OptionCardDescription } from '@customerio/pluma-components/react';

Custom title

Custom content

Visit our docs.

<OptionCard
	value="test_value"
>
	<OptionCardTitle>Custom title</OptionCardTitle>
	<OptionCardDescription>
		<Text as="p">Custom content</Text>
		<Text as="p">
			Visit our <Link href="https://customer.io/docs" isExternal={true}>docs</Link>.
		</Text>
	</OptionCardDescription>
</OptionCard>

Preventing selection

You can prevent cards from being selected, but still allow deselecting them, with the canSelect prop. This is different from the isDisabled prop, which disabled selections and deselections entirely.

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

one

two

three

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

export default function Example() {
	const [selections, setSelections] = useState({one: false, two: true, three: true});

	return <Box 
		display="flex"
		gap="200"
	>
		{['one', 'two', 'three'].map((key) => (
			<OptionCard
				key={key}
				value={key}
				title={key}
				inputType="checkbox"
				canSelect={Object.values(selections).filter((v) => v === true).length < 2}
				isSelected={selections[key]}
				onCheckedChange={(checked) => {
					setSelections({
						...selections,
						[key]: checked
					});
				}}
			/>
		))}
	</Box>
}

API

`PlumaOptionCard` `extends Box`

`ariaDescribedby` `string | undefined`

Element (or elements) that describe the form field. Also used for error messages, as aria-errormessage isn't supported in all assistive technologies: https://a11ysupport.io/tech/aria/aria-errormessage_attribute

`ariaLabel` `string | undefined`

String value that labels the form field.

`ariaLabelledby` `string | undefined`

Element (or elements) that label the form field.

`canSelect` `boolean | undefined`

This option prevents selection of the card. Unlike isDisabled, however, it will not prevent the deselection, if currently selected.

`description` `string | undefined`

An additional description to be shown in the card.

`error` `string | boolean | undefined`

An error message associated with the form field. Boolean: Ember-only. If the error named block is used, this prop can be set to true to indicate an error is present, which will make the error block render.

`icon` `IconName | null | undefined`

The name of an icon (from Pluma Icons) to render in the card.

`iconSrc` `string | undefined`

The source URL of a custom image icon to render in the card. When provided, this will be rendered using the Image component with icon sizing. The image will always have alt="" as it is purely decorative - meaning comes from card title or aria-label.

`id` `string | undefined`

An optional id to be assigned to the input element. Also used to generate ids for labels and error messages. If one isn't provided, it will be generated.

`inputType` `"checkbox" | "radio" | undefined`

Default:radio

Whether the card represents a radio or a checkbox input.

`isDisabled` `boolean | undefined`

Whether the form field is disabled.

`isInvalid` `boolean | undefined`

Whether the form field is in an invalid state.

`isSelected` `boolean | undefined`

Whether the card is in the "selected" state.

`layout` `"horizontal" | "vertical" | undefined`

Default:horizontal

Controls the layout and text alignment of the card. In horizontal layout, content is left-aligned; in vertical layout, content is centered. When an icon or iconSrc is present, also controls the position of the icon relative to the card content.

`name` `string | undefined`

The name shared by cards in the same group.

`onChange` `(e: Event | ChangeEvent<HTMLInputElement>) => void`

The change event handler for the input element. Fired when a card is selected or deselected. Exact behavior depends on whether it's a checkbox or a radio. In React, the event is a React SyntheticEvent; in Ember it's a native change event.

`onCheckedChange` `((checked: boolean, event: OnChangeArgType) => void) | undefined`

Callback fired when the state of the option card changes.

`shouldAllowAutofill` `boolean | undefined`

Whether to allow browser autofill and password managers. When false (default), adds attributes to disable password managers (1Password, LastPass, Bitwarden, Dashlane). Set to true for fields where autofill is desired (e.g., email, password, address fields).

OptionCard

PlumaOptionCard extends Box

ariaDescribedby string | undefined

ariaLabel string | undefined

ariaLabelledby string | undefined

canSelect boolean | undefined

description string | undefined

error string | boolean | undefined

icon IconName | null | undefined

iconSrc string | undefined

id string | undefined

inputType "checkbox" | "radio" | undefined

isDisabled boolean | undefined

isInvalid boolean | undefined

isSelected boolean | undefined

layout "horizontal" | "vertical" | undefined

name string | undefined

onChange (e: Event | ChangeEvent<HTMLInputElement>) => void

onCheckedChange ((checked: boolean, event: OnChangeArgType) => void) | undefined

shouldAllowAutofill boolean | undefined

shouldAppendAriaDescribedbyId boolean | undefined

shouldAppendAriaLabelledbyId boolean | undefined

shouldValidateLabelPresence boolean | undefined

size "sm" | "md" | undefined

title string | undefined

unsafe_fieldClassName string | undefined

unsafe_hasLabelBlock boolean | undefined

unsafe_inputClassName string | undefined

unsafe_inputSize number | undefined

unsafe_isLegacy boolean | undefined

value string | undefined

withCenterBaseline boolean | undefined

On this page

`PlumaOptionCard` `extends Box`

`ariaDescribedby` `string | undefined`

`ariaLabel` `string | undefined`

`ariaLabelledby` `string | undefined`

`canSelect` `boolean | undefined`

`description` `string | undefined`

`error` `string | boolean | undefined`

`icon` `IconName | null | undefined`

`iconSrc` `string | undefined`

`id` `string | undefined`

`inputType` `"checkbox" | "radio" | undefined`

`isDisabled` `boolean | undefined`

`isInvalid` `boolean | undefined`

`isSelected` `boolean | undefined`

`layout` `"horizontal" | "vertical" | undefined`

`name` `string | undefined`

`onChange` `(e: Event | ChangeEvent<HTMLInputElement>) => void`

`onCheckedChange` `((checked: boolean, event: OnChangeArgType) => void) | undefined`

`shouldAllowAutofill` `boolean | undefined`

`shouldAppendAriaDescribedbyId` `boolean | undefined`

`shouldAppendAriaLabelledbyId` `boolean | undefined`

`shouldValidateLabelPresence` `boolean | undefined`

`size` `"sm" | "md" | undefined`

`title` `string | undefined`

`unsafe_fieldClassName` `string | undefined`

`unsafe_hasLabelBlock` `boolean | undefined`

`unsafe_inputClassName` `string | undefined`

`unsafe_inputSize` `number | undefined`

`unsafe_isLegacy` `boolean | undefined`

`value` `string | undefined`

`withCenterBaseline` `boolean | undefined`