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>
  );
};

API Reference

`SelectableCards`

Contains all the parts of a selectable card group.

Inherits properties from HTMLElement.

Prop	Type	Default
`align`	`"row""column"`	`"column"`
`children`	`ReactNode`
`className`	`string`
`defaultValue`	`string \| string[]`
`disabled`	`boolean`
`justify`	`"start""center"`	`"center"`
`label`	`string`
`loop`	`boolean`	`true`
`name`	`string`
`onValueChange`	`(value: string \| string[]) => void`
`orientation`	`"horizontal""vertical"`	`"horizontal"`
`required`	`boolean`
`theme`	`"light""dark"`	`"light"`
`type`	`"single""multiple"`	`"single"`
`value`	`string \| string[]`

`SelectableCard`

An item in the group that can be checked. An input will also render when used within a form to ensure events propagate correctly.

Inherits properties from HTMLButtonElement.

Prop	Type	Default
`label`	`string`
`value`	`string`
`children`	`ReactNode`
`className`	`string`
`disabled`	`boolean`
`icon`	`IconProp`
`selectedIcon`	`IconProp`

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