ChoiceBox

ChoiceBox is a checkbox wrapped in a card-like container. It's used in question/answer scenarios where it's useful to show additional information for each option.

• Figma
• Storybook
• Edit this page
• Create a new issue

Option 1

Code example

import { ChoiceBox } from '@yleisradio/yds-components-react';

<ChoiceBox name="choice-1" label="Option 1" />

Why to use

ChoiceBox gives you a consistent, accessible way to present multi-select options in a card layout. It extends Checkbox with an optional icon, extra content below the label, and right/wrong answer indicator — so you can highlight options or show results without building custom layouts.

When to use

Use ChoiceBox when options need a card-style container: each choice has an icon, a short description, or should stand out visually. Use plain Checkbox when options are simple labels in a list.

Do

• Use for question/answer patterns.

Don't

• Don't use as a regular form component. Use Checkbox instead.

Content guidelines

Keep labels short and parallel. Put longer explanations in the content prop or in a group description.

Do

• Use the optional icon and status to tell the user if the answer is correct or incorrect.
• Use content for brief supporting text, not for the main choice label.

Don't

• Don't use long sentences as the main label — move detail into content or description.

Key ChoiceBox Props

Use these props to configure the ChoiceBox component.

label

Label text or content for the checkbox.

Type	Example	Description
React.ReactNode	Option 1	Label content for the checkbox

Code example

<ChoiceBox name="option-1" label="Option 1" />
<ChoiceBox name="option-2" label={<strong>Bold Option</strong>} />

status

Visual status indicator for the choice box.

Value	Example	Description
success	Option	Success status styling
error	Option	Error status styling

Code example

<ChoiceBox name="option-1" label="Option" status="success" />
<ChoiceBox name="option-2" label="Option" status="error" />

controlAlign

Alignment of the checkbox control relative to the content.

Value	Example	Description
start	Option	Aligns control to the start
end	Option	Aligns control to the end

Code example

<ChoiceBox name="option-1" label="Option" controlAlign="start" />
<ChoiceBox name="option-2" label="Option" controlAlign="end" />

containerSize

Size of the choice container.

Value	Example	Description
sm	Option	Small container size
md	Option	Medium container size (default)

Code example

<ChoiceBox name="option-1" label="Option" containerSize="sm" />
<ChoiceBox name="option-2" label="Option" containerSize="md" />

icon

Optional icon to display in the choice container.

Type	Example	Description
React.ReactNode	Option	Icon element to display. Use with status to tell the user if the answer is correct or incorrect.

Code example

import { Check } from '@yleisradio/yds-icons-react';

<ChoiceBox name="option-1" label="Option" icon={<Check />} />

content

Additional content to display below the checkbox and icon.

Type	Example	Description
React.ReactNode	Option Some additional content	Additional content below the control

Code example

<ChoiceBox
  name="option-1"
  label="Option"
  content={<p style={{ margin: 16 }}>Some additional content</p>}
/>

isDisabled

Whether the checkbox is disabled.

Type	Example	Description
boolean	Option	Disables the checkbox

Code example

<ChoiceBox name="option-1" label="Option" isDisabled />

variant

Visual style variant of the checkbox.

Value	Example	Description
primary	Option	Primary variant (default)
secondary	Option	Secondary variant

Code example

<ChoiceBox name="option-1" label="Option" variant="primary" />
<ChoiceBox name="option-2" label="Option" variant="secondary" />

useUnderlay

Whether to show an underlay effect.

Type	Example	Description
boolean	Option	Shows underlay effect

Code example

<ChoiceBox name="option-1" label="Option" useUnderlay />

background

Background style variant of the choice container.

Type	Example	Description
default	Option	Default background
variant	Option	Variant background

Code example

<ChoiceBox name="option-1" label="Option" background="default" />
<ChoiceBox name="option-2" label="Option" background="variant" />

Behavior

• Each ChoiceBox is independent; multiple can be selected or none. Use the same name for options that belong to the same question.
• Checked state is controlled via checked / defaultChecked; use onChange for controlled usage.
• The container has an underlay by default (useUnderlay={true}).
• status="success" or status="error" applies visual feedback.
• Disabled options are non-interactive but remain visible.

Accessibility

• Every ChoiceBox must have a visible or programmatically associated label (use label with meaningful accessible name).
  (WCAG 3.3.2 — Labels or Instructions)
• Group related options under a shared question or fieldset so the relationship is clear.
  (WCAG 1.3.1 — Info and Relationships)
• Keyboard: Tab/Shift+Tab move focus; Space toggles the focused checkbox.
  (WCAG 2.1.1 — Keyboard)

API Reference

Props

The ChoiceBox component accepts all standard HTML <input> attributes (except size) in addition to the following props:

Prop	Type	Required	Default	Description
name	string	Yes	—	Name attribute for form submission
label	React.ReactNode	Yes	—	Label content for the checkbox
status	'success' | 'error'	No	—	Visual status indicator
controlAlign	'start' | 'end'	No	—	Alignment of checkbox control
containerSize	'sm' | 'md'	No	—	Size of the choice container
icon	React.ReactNode	No	—	Optional icon to display
content	React.ReactNode	No	—	Additional content below control
isDisabled	boolean	No	false	Whether the checkbox is disabled
variant	'primary' | 'secondary'	No	'primary'	Visual style variant
value	string	No	—	Value attribute for form submission
hideLabel	boolean	No	false	Visually hides the label
useUnderlay	boolean	No	true	Shows underlay effect
background	'default' | 'variant'	No	'default'	Background style variant

Type Definitions

export type ChoiceContainerStatus = 'success' | 'error';
export type ChoiceContainerBackground = 'default' | 'variant';
export type InputControlAlign = 'start' | 'end';
export type ChoiceContainerSize = 'sm' | 'md';
export type ChoiceHTMLInputAttributes = Omit<InputHTMLAttributes<HTMLInputElement>, 'size'>;

export interface ChoiceBoxDSProps {
  status?: ChoiceContainerStatus;
  controlAlign?: InputControlAlign;
  containerSize?: ChoiceContainerSize;
  icon?: React.ReactNode;
  content?: React.ReactNode;
  background?: ChoiceContainerBackground;
}

export type CheckboxPropsNoError = Omit<CheckboxProps, 'error'>;

export type ChoiceBoxProps = ChoiceHTMLInputAttributes & ChoiceBoxDSProps & CheckboxPropsNoError;

Related Components

• Checkbox – Base checkbox component for grouping multiple selections with a shared label and validation.
• ChoiceButton – Card-style single-select option (radio).