Skip to Content
BBRICKSv0.7.4
PR PortalForms and dialogs

ChoiceGroup

The PR mock's .choice cards ("% of sale" / "Fixed per item", Leaderboard / Target, Public / Affiliates only, Cash / Gift): a radio group drawn as cards, an icon square, a bold title and a muted line; the chosen card gets the ink edge. Arrow keys move and choose (skipping disabled cards), Home / End jump; one tab stop.

import { ChoiceGroup } from '@ergasti/bricks';

Examples

Choose one of a few

Cards with an icon, a title and a description, in a radio group; arrow keys move, and columns sets the layout. icon is a PrIcon name or an element: "% of sale" shows the mock's bold "%" (icon: <b>%</b>).

Code
import { useState } from 'react';
import { ChoiceGroup } from '@ergasti/bricks';

function Earn() {
  const [value, setValue] = useState<'pct' | 'fixed' | null>('pct');
  return (
    <ChoiceGroup
      label="How creators earn" value={value} onChange={setValue}
      options={[
        { value: 'pct', title: '% of sale', description: 'A share of each delivered order', icon: <b>%</b>, tone: 'rasp' },
        { value: 'fixed', title: 'Fixed per item', description: 'A set amount per item sold', icon: 'cash', tone: 'sky' },
      ]}
    />
  );
}

One column

columns={1} stacks the cards (also 3 for three across); with no choice made, value is null and no card is selected.

Code
import { useState } from 'react';
import { ChoiceGroup } from '@ergasti/bricks';

function Stacked() {
  const [value, setValue] = useState<'brand' | 'public' | null>(null);
  return (
    <div style={{ maxWidth: 420 }}>
      <ChoiceGroup
        label="Who can join" value={value} onChange={setValue} columns={1}
        options={[
          { value: 'public', title: 'Every creator', description: 'Anyone on TRNDR who matches the rules', icon: 'creators', tone: 'lime' },
          { value: 'brand', title: 'This brand’s creators', description: 'Only creators already in the program', icon: 'brands', tone: 'lilac' },
        ]}
      />
    </div>
  );
}

Props

Prop

Type

Design guidance

How the BRICKS design system uses ChoiceGroup. Written in docs/content/components/ChoiceGroup.md; the props above are read from the code, which wins where the two disagree.

A radio group drawn as cards, each with a tinted icon square, a bold title and a muted line; use it in PR forms for a choice of two or three options that need a sentence each.

ChoiceGroup is the PR mock's .choice cards: "% of sale" / "Fixed per item", Leaderboard / Target, Public / Affiliates only, Cash / Gift. The chosen card gets an ink edge. It behaves as one radio group: a single tab stop, arrow keys move and choose (skipping disabled cards), Home / End jump. A disabled card stays visible with its reason as the line. ChannelPicker is built on it.

Anatomy

  1. Group: <div role="radiogroup" aria-label>, a grid of 1, 2 or 3 columns, 14px gap (one column under 600px).
  2. Card: <button role="radio" aria-checked>, 16px padding, 1.5px --line border, radius 18px; chosen: ink border plus a 1px ink ring.
  3. Icon square: IconSquare size="sm" (38px) in the option's tone (default mute), or any element in the same square (the mock's bold "%").
  4. Text: bold title over a 12.5px --ink-3 description.

Variants

PropValueLookWhen to use
columns2 (default)Two cards per rowTwo options
3Three per rowThree options (channels, challenge types)
1StackedLong descriptions, narrow columns
option iconPrIconNameIconSquareMost options
elementGlyph in the tinted square"%", a currency sign
option tonerasp, butter, sky, lime, lilac, muteSquare tintDistinguish options

States

StateTrigger
Nothing chosenvalue={null}: the first enabled card is the tab stop
Chosenvalue matches: ink edge, aria-checked="true"
Hoverborder --color-control-border-hover (enabled only)
Focus-visiblefocus ring (plus the ink ring when chosen)
Disabledoption disabled: 55% opacity, not-allowed cursor, skipped by arrows

Types

ChoiceOption.icon: a PrIconName or a ReactElement (not any string, so a typo is a type error).

ChoiceOption<T> (options): { value, title, description?, icon?, tone?, disabled? }.

Usage

import { ChoiceGroup } from '@ergasti/bricks';

<ChoiceGroup
  label="How creators earn"
  value={type}
  onChange={setType}
  options={[
    { value: 'pct', title: '% of sale', description: 'A share of each delivered order', icon: <b>%</b>, tone: 'rasp' },
    { value: 'egp', title: 'Fixed per item', description: 'A set amount per item sold', icon: 'cash', tone: 'sky' },
  ]}
/>
// Campaign page › Change the commission: the choice, the field and What changes
<Card title="Change the commission">
  <ChoiceGroup label="How creators earn" value={type} onChange={setType} options={earnOptions} />
  <FormField label="Commission" hint="% of each delivered order">
    <input inputMode="decimal" value={rate} onChange={(e) => setRate(e.target.value)} />
  </FormField>
  <ChangePreview from="10% of sale" to="12% of sale" changed={rate !== '10'}
    example={<>On an EGP 1,000 order, the creator earns <b>EGP 120</b>.</>}
    note="Applies to orders placed after you save. Orders already placed keep the old rate." />
</Card>

One column. columns={1} stacks the cards (also 3 for three across); with no choice made, value is null and no card is selected. (docs example Stacked)

import { useState } from 'react';
import { ChoiceGroup } from '@ergasti/bricks';

export function Stacked() {
  const [value, setValue] = useState<'brand' | 'public' | null>(null);
  return (
    <div style={{ maxWidth: 420 }}>
      <ChoiceGroup
        label="Who can join" value={value} onChange={(next) => setValue(next as 'brand' | 'public')} columns={1}
        options={[
          { value: 'public', title: 'Every creator', description: 'Anyone on TRNDR who matches the rules', icon: 'creators', tone: 'lime' },
          { value: 'brand', title: 'This brand’s creators', description: 'Only creators already in the program', icon: 'brands', tone: 'lilac' },
        ]}
      />
    </div>
  );
}

Where it appears

  • PR Portal › Affiliate programs › Campaigns › a campaign's page › "How creators earn" (% of sale / Fixed per item).
  • PR Portal › Affiliate programs › Challenges › challenge builder › Type & goal (Leaderboard / Target), Who can join (Public / Affiliates only), Reward (Cash / Gift).
  • PR Portal › Messages › composer channel (via ChannelPicker).
  • Dashboard screen: PrPrograms.

Guidelines

Do

  • Keep titles to two or three words and descriptions to one line.
  • Say why a disabled option is unavailable in its description.
  • Use different tones per option so the squares help scanning.

Don't

  • Don't use it for more than three options or for yes/no (use a Switch).
  • Don't put links or buttons inside a card: the card is a button.

RTL and Arabic

The grid and cards mirror (text-align: start). Arrow keys follow the reading direction through rovingNext. Pass Arabic titles and descriptions in options.

Tokens

--line, --card, --ink, --ink-3, --color-control-border-hover, --focus-ring, plus IconSquare tones.

Accessibility

  • role="radiogroup" with aria-label; each card is role="radio" with aria-checked.
  • One tab stop (the chosen card, or the first enabled one); arrows move and select, Home / End jump; disabled cards are skipped.
  • Icon squares are aria-hidden; the title and description are the accessible name.

Found in the source

  • Roles in the markup: radio, radiogroup.
  • ARIA attributes set: aria-label, aria-checked, aria-hidden.
  • It moves focus in code.
  • Its tests cover: “click chooses; arrows move and choose, skipping the disabled card, wrapping”.

Read from the component's source and tests. See Accessibility for the patterns the library follows.

  • ChannelPicker: ChoiceGroup for message channels.
  • Segmented (kit): a compact switch between views, not a form choice.
  • Switch (kit): on / off.

See also: IconSquare · BulkAction · ChangePreview · DecisionsCard · FigureRow

Source

src/pr/ChoiceGroup.tsx (line 31) on GitHub.

On this page