ChoiceCards

A visual card picker for choosing one or multiple options from a compact set.

Import

import { ChoiceCards } from "@schukai/monster/source/components/form/choice-cards.mjs";

Source

View source code

Package

@schukai/monster

Since

4.137.0

Team workspace Enterprise controls

Introduction

The Monster ChoiceCards component is a single-choice control that presents options as compact cards instead of a dropdown. Use it when the choices are few, visible at once and important enough to compare before selecting.

When to use ChoiceCards

Use it for visible single-choice decisions: Shipping method, billing cadence, account type or plan tier choices are good fits.
Use it when labels need more context: The contentSlot item field lets each card show richer content while keeping the submitted value explicit.
Do not use it for large option sets: For long lists, filtering, remote lookup or multi-select, use Select instead.

Item model

Each item is normalized into an object with a stable value and label. Strings and numbers are accepted as shortcuts, but object items are clearer for production code.

choiceCards.setItems([
    {value: "standard", label: "Standard"},
    {value: "express", label: "Express", contentSlot: "express-card"},
    {value: "pickup", label: "Pickup", disabled: true}
]);

Events

User selection emits the native change event followed by monster-selected, monster-change and monster-changed. The custom event detail contains the selected value and the normalized item.

Typical mistakes

Do not treat card text as the submitted value by accident. Keep value stable and use label or slotted content for human-readable copy. If the component is configured from JavaScript, wait for customElements.whenDefined("monster-choice-cards") before calling public methods.

Simple Card Choices

This example configures monster-choice-cards with object items, custom card slots and a stable submitted value. The status text is updated from the documented monster-change event detail.

Delivery Send the order to the customer address. Pickup Reserve the order for collection today. Hold Keep the order in review until stock is confirmed.

Selected value: pickup

Javascript

import "@schukai/monster/source/components/form/choice-cards.mjs";

await customElements.whenDefined("monster-choice-cards");

const choiceCards = document.getElementById("fulfillment-choice");
const status = document.getElementById("fulfillment-choice-status");

choiceCards.setItems([
  {
    value: "delivery",
    label: "Delivery",
    contentSlot: "delivery-card",
  },
  {
    value: "pickup",
    label: "Pickup",
    contentSlot: "pickup-card",
  },
  {
    value: "hold",
    label: "Hold",
    contentSlot: "hold-card",
  },
]);

choiceCards.addEventListener("monster-change", (event) => {
  status.textContent = "Selected value: " + event.detail.value;
});

HTML

<section class="choice-cards-example">
  <monster-choice-cards id="fulfillment-choice" value="pickup">
    <span class="choice-card-content" slot="delivery-card">
      <strong>Delivery</strong>
      <small>Send the order to the customer address.</small>
    </span>
    <span class="choice-card-content" slot="pickup-card">
      <strong>Pickup</strong>
      <small>Reserve the order for collection today.</small>
    </span>
    <span class="choice-card-content" slot="hold-card">
      <strong>Hold</strong>
      <small>Keep the order in review until stock is confirmed.</small>
    </span>
  </monster-choice-cards>

  <p id="fulfillment-choice-status" class="choice-cards-status">
    Selected value: pickup
  </p>
</section>

Stylesheet

.choice-cards-example {
  display: grid;
  gap: var(--monster-space-4);
}

.choice-cards-example monster-choice-cards {
  --monster-choice-cards-card-width: 12rem;
  --monster-choice-cards-gap: var(--monster-space-3);
}

.choice-card-content {
  display: grid;
  gap: var(--monster-space-2);
}

.choice-card-content small {
  color: var(--monster-color-primary-1);
  line-height: 1.35;
}

.choice-cards-status {
  color: var(--monster-color-primary-1);
  margin: 0;
}

Open in playground

Component Design

ChoiceCards renders a form-associated radio-card group in Shadow DOM. The host owns focus handling, keyboard selection and form value synchronization while the page supplies options through documented item data.

Public styling surface

Style the component through Monster tokens, component custom properties and documented parts. Do not depend on internal button or indicator nodes.

Available Part Attributes

control: The radiogroup container.
items: The flex container that receives the generated choice buttons.

Useful custom properties

--monster-choice-cards-gap: Space between cards.
--monster-choice-cards-card-width: Preferred card width.
--monster-choice-cards-min-height: Minimum card height.

monster-choice-cards {
    --monster-choice-cards-card-width: 12rem;
    --monster-choice-cards-gap: var(--monster-space-4);
}

monster-choice-cards::part(items) {
    align-items: stretch;
}

Accessibility

The component exposes a radio group, keeps the current value synchronized and supports keyboard selection. Use labels.group when the surrounding page does not already provide enough context for the choice group.

HTML Structure

<monster-choice-cards></monster-choice-cards>

JavaScript Initialization

const element = document.createElement('monster-choice-cards');
document.body.appendChild(element);

Exported

ChoiceCards

Derived from

CustomControl

Options

The Options listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class. Therefore, it inherits Options from these parent classes. If you cannot find a specific Options in this list, we recommend consulting the documentation of the CustomControl.

Option

Type

Default

Description

items

array<object|string|number>

undefined

Choice items. String and number entries are converted to `{value,label}` objects.

items[].id

string

undefined

Stable item identifier. Defaults to the item value or a generated `item-{index}` id.

items[].value

string

undefined

Submitted and selected value.

items[].label

string

undefined

Visible and accessible label for generated card content.

items[].iconSlot

string

undefined

Slot name for custom icon content.

items[].contentSlot

string

undefined

Slot name for custom card content. The shorter `slot` field is accepted as alias.

items[].disabled

boolean

undefined

Disables a single choice while keeping it visible.

value

string|null|array<string>

Current selected value. Multi-select mode uses an array.

multiple

boolean

false

Enables independent on/off selection for multiple cards.

disabled

boolean

false

Disabled state.

labels

object

Accessible labels.

labels.group

string

Choices

Radio group label.

templates

object

Template definitions.

templates.main

string

undefined

Main template.

since
deprecated

Properties and Attributes

The Properties and Attributes listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits Properties and Attributes from these parent classes. If you cannot find a specific Properties and Attributes in this list, we recommend consulting the documentation of the CustomControl.

data-monster-options: Sets the configuration options for the collapse component when used as an HTML attribute.
data-monster-option-[name]: Sets the value of the configuration option [name] for the collapse component when used as an HTML attribute.

Methods

The methods listed in this section are defined directly within the class. This class is derived from several parent classes, including the CustomElement class and ultimately from HTMLElement. Therefore, it inherits methods from these parent classes. If you cannot find a specific method in this list, we recommend consulting the documentation of the CustomControl.

State query methods

value()

Returns

{string|null|Array}

No description available.

value(value)

Parameters

value {string|array<string>|null|undefined}: value

No description available.

Structural methods

getItems()

Returns

{Array}

No description available.

setItems(items)

Parameters

items {array}: items

Returns

{ChoiceCards}

No description available.

Static methods

[instanceSymbol]()

Returns

{symbol}

This method is called by the instanceof operator.

getCSSStyleSheet()

Returns

{CSSStyleSheet[]}

No description available.

getTag()

Returns

{string}

No description available.

Lifecycle methods

Lifecycle methods are called by the environment and are usually not intended to be called directly.

[assembleMethodSymbol]()

Returns

{void}

No description available.

Other methods

select(value)

Parameters

value {string|null|undefined}: value

Returns

{ChoiceCards}

Select a choice by value.

Events

The component emits the following events:

monster-selected
monster-change
monster-changed

For more information on how to handle events, see the mdn documentation.

The current width of the area is too small to display the content correctly.