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
- Group:
<div role="radiogroup" aria-label>, a grid of 1, 2 or 3 columns, 14px gap (one column under 600px). - Card:
<button role="radio" aria-checked>, 16px padding, 1.5px--lineborder, radius 18px; chosen: ink border plus a 1px ink ring. - Icon square:
IconSquare size="sm"(38px) in the option'stone(defaultmute), or any element in the same square (the mock's bold "%"). - Text: bold title over a 12.5px
--ink-3description.
Variants
| Prop | Value | Look | When to use |
|---|---|---|---|
columns | 2 (default) | Two cards per row | Two options |
3 | Three per row | Three options (channels, challenge types) | |
1 | Stacked | Long descriptions, narrow columns | |
option icon | PrIconName | IconSquare | Most options |
| element | Glyph in the tinted square | "%", a currency sign | |
option tone | rasp, butter, sky, lime, lilac, mute | Square tint | Distinguish options |
States
| State | Trigger |
|---|---|
| Nothing chosen | value={null}: the first enabled card is the tab stop |
| Chosen | value matches: ink edge, aria-checked="true" |
| Hover | border --color-control-border-hover (enabled only) |
| Focus-visible | focus ring (plus the ink ring when chosen) |
| Disabled | option 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"witharia-label; each card isrole="radio"witharia-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.
Related
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.