Selectable Cards

Set of interactive cards where one or more can be selected at a time.

Usage

Put one or more SelectableCard components inside SelectableCards.

Display density

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";

export default () => (
  <SelectableCards defaultValue="default" label="Display density">
    <SelectableCard value="default" label="Default" />
    <SelectableCard value="comfortable" label="Comfortable" />
    <SelectableCard value="compact" label="Compact" />
  </SelectableCards>
);

Icons

Import and pass a FontAwesome icon to icon to display it beside the label on the card. To display a different icon when the card is selected, pass a FontAwesome icon to selectedIcon. This is helpful for toggling between regular and solid icon states.

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";
import { faImage, faVideo, faMusic } from "@fortawesome/pro-regular-svg-icons";
import {
  faImage as faSolidImage,
  faVideo as faSolidVideo,
  faMusic as faSolidMusic,
} from "@fortawesome/pro-solid-svg-icons";

export default () => (
  <SelectableCards defaultValue="image">
    <SelectableCard
      value="image"
      icon={faImage}
      selectedIcon={faSolidImage}
      label="Image"
    />
    <SelectableCard
      value="video"
      icon={faVideo}
      selectedIcon={faSolidVideo}
      label="Video"
    />
    <SelectableCard
      value="music"
      icon={faMusic}
      selectedIcon={faSolidMusic}
      label="Music"
    />
  </SelectableCards>
);

Layout and alignment

Control the layout and alignment of content within each card using the align and justify props.

Orientation

By default, cards are arranged in equal-width columns (orientation="horizontal"). To display them in a vertical flex column layout instead, pass orientation="vertical". The keys used to switch between elements will change from ← and → to ↑ and ↓.

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";
import { faImage, faVideo, faMusic } from "@fortawesome/pro-regular-svg-icons";
import {
  faImage as faSolidImage,
  faVideo as faSolidVideo,
  faMusic as faSolidMusic,
} from "@fortawesome/pro-solid-svg-icons";

export default () => (
  <SelectableCards orientation="vertical" align="row" defaultValue="image">
    <SelectableCard
      value="image"
      icon={faImage}
      selectedIcon={faSolidImage}
      label="Image"
    />
    <SelectableCard
      value="video"
      icon={faVideo}
      selectedIcon={faSolidVideo}
      label="Video"
    />
    <SelectableCard
      value="music"
      icon={faMusic}
      selectedIcon={faSolidMusic}
      label="Music"
    />
  </SelectableCards>
);

Multi-select

By default, SelectableCards allows only one selection at a time. To allow multiple selections, set type to "multiple".

Accessibility

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";

export default () => (
  <SelectableCards
    type="multiple"
    defaultValue={["high-contrast", "reduce-motion"]}
    label="Accessibility"
  >
    <SelectableCard value="high-contrast" label="High Contrast" />
    <SelectableCard value="reduce-motion" label="Reduce Motion" />
    <SelectableCard value="enlarge-text" label="Enlarge Text" />
  </SelectableCards>
);

Multi-select works with all the same features as single-select, including icons:

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";
import { faImage, faVideo, faMusic } from "@fortawesome/pro-regular-svg-icons";
import {
  faImage as faSolidImage,
  faVideo as faSolidVideo,
  faMusic as faSolidMusic,
} from "@fortawesome/pro-solid-svg-icons";

export default () => (
  <SelectableCards type="multiple" defaultValue={["image", "video"]}>
    <SelectableCard
      value="image"
      icon={faImage}
      selectedIcon={faSolidImage}
      label="Image"
    />
    <SelectableCard
      value="video"
      icon={faVideo}
      selectedIcon={faSolidVideo}
      label="Video"
    />
    <SelectableCard
      value="music"
      icon={faMusic}
      selectedIcon={faSolidMusic}
      label="Music"
    />
  </SelectableCards>
);

Disabled

The entire group can be disabled by using the disabled prop on SelectableCards. Beware of accessibility drawbacks when disabling buttons.

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";

export default () => (
  <SelectableCards disabled defaultValue="default">
    <SelectableCard value="default" label="Default" />
    <SelectableCard value="comfortable" label="Comfortable" />
    <SelectableCard value="compact" label="Compact" />
  </SelectableCards>
);

The disabled prop can also be used to disable a specific SelectableCard.

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";

export default () => (
  <SelectableCards defaultValue="default">
    <SelectableCard value="default" label="Default" />
    <SelectableCard value="comfortable" label="Comfortable" />
    <SelectableCard value="compact" label="Compact" disabled />
  </SelectableCards>
);

Controlled state

By default, SelectableCards is uncontrolled. To make it controlled, set value and onValueChange.

Density

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";
import { useState } from "react";

export default () => {
  const [radioValue, setRadioValue] = useState("default");

  return (
    <SelectableCards
      value={radioValue}
      onValueChange={setRadioValue}
      label="Density"
    >
      <SelectableCard value="default" label="Default" />
      <SelectableCard value="comfortable" label="Comfortable" />
      <SelectableCard value="compact" label="Compact" />
    </SelectableCards>
  );
};

For multi-select, use an array for the value and onValueChange parameters:

Accessibility

import { SelectableCards, SelectableCard } from "stylus-ui/SelectableCards";
import { useState } from "react";

export default () => {
  const [selectedValues, setSelectedValues] = useState(["default"]);

  return (
    <SelectableCards
      type="multiple"
      value={selectedValues}
      onValueChange={setSelectedValues}
      label="Accessibility"
    >
      <SelectableCard value="high-contrast" label="High Contrast" />
      <SelectableCard value="reduce-motion" label="Reduce Motion" />
      <SelectableCard value="enlarge-text" label="Enlarge Text" />
    </SelectableCards>
  );
};

Keyboard Controls

Key	Description
`Tab`	Move focus into and out of the selectable cards group
`↑` `↓`	Navigate between options (vertical layout)
`←` `→`	Navigate between options (horizontal layout)
`Space`	Toggle focused option
`Home`	Jump to first option
`End`	Jump to last option

API Reference

`SelectableCards`

`align`

"row" | "column" = "column"

Card layout: row (icon + text) or column.

`children`

ReactNode

SelectableCard components.

`className`

string

Optional class for the container.

`defaultValue`

string

`disabled`

boolean

Disable all cards.

`justify`

"center" | "start" = "start"

Alignment of content within each card.

`label`

string

Accessible label for the group (e.g. for screen readers).

`loop`

boolean

Whether focus loops when navigating with keyboard.

`name`

string

Form name for the underlying input group.

`onValueChange`

(value: string) => void

`orientation`

"horizontal" | "vertical" = "vertical"

Layout: horizontal grid or vertical stack.

`required`

boolean

Mark the selection as required for forms.

`theme`

"light" | "dark" = "light"

Visual theme.

`type`

"single"

`value`

string

`SelectableCard`

Displays a single selectable card. Must be rendered inside SelectableCards.

`label`

Required

string

Main label text.

`value`

Required

string

Value submitted when this card is selected (single or part of multiple selection).

`children`

ReactNode

Additional content below the label.

`className`

string

Optional class for the card.

`disabled`

boolean

Disable this card only.

`icon`

IconDefinition

Icon shown when the card is not selected.

`selectedIcon`

IconDefinition

Icon shown when the card is selected (overlays or replaces icon).