Choice list

Overview

A choice list is a question and its answers. The header names the question; the items list the answers; the optional inline message handles validation errors. Three item types ship in the same wrapper — radio button, checkbox, and radio card — and each one tells the user a different thing about how the selection works.

Anatomy

Three regions stacked vertically: the header up top, the items in the middle, and the optional inline error at the bottom. 16 px gap between every adjacent pair, regardless of which region is showing.

Types

Three item types share the same wrapper. Pick by the selection model — exclusive vs not — and by how much each option needs to explain itself.

Header

Header is optional. Use a label whenever the question isn't already obvious from the page; add the subline when the label needs a constraint, a price, or a soft hint that doesn't fit on each item.

Error

When the user submits without picking (or with an invalid pick), the choice list flips into error mode: every item gets the danger ring, and a single inline message appears at the bottom. Don't paint required-but-untouched groups red preemptively.

Behavior

• 01Selection model is fixed by type. Radio button + radio card = mutually exclusive, one always selected. Checkbox = multi-select, zero or more. Don't mix types in the same list.
• 02Whole row is the click target. Clicking the title, the help text, or the radio card's body all toggle the selection — same as clicking the mark. Hit area extends the row width.
• 03Error tone applies to the whole group. When validation fails, every item ring goes red and a single inline message names the problem. Don't mark just one item — the user picked nothing, not the wrong thing.
• 04Radio cards lay out horizontally on desktop, stack on mobile. They need room to breathe — three lines of supporting text and a ~20 px radio mark per card. Below 600 px viewport, the cards stack and take the full row.
• 05Default to a sensible pick for radio types. The list never ships empty. For checkboxes, default state is whatever the user last saved (or all-off, never all-on for opt-ins).

Accessibility

• Wrap in <fieldset> with <legend> so screen readers announce the question before the options. The label and subline both live inside the legend; the subline gets a visually-hidden colon between them.
• Native inputs underneath. <input type="radio"> with a shared name, or <input type="checkbox"> for the multi case. The browser handles arrow-key nav (radios) and Space-to-toggle (checkboxes) for free.
• Subline links via aria-describedby on the fieldset, pointing at the subline's id. Screen readers announce it together with the legend.
• Error linking: aria-invalid="true" on the fieldset and aria-describedby extended to include the error message. Wrap the message in aria-live="polite" so it announces when it appears.
• Disabled options stay in the DOM with aria-disabled="true" so screen readers announce them. Pair with helper copy explaining why — “Available once your POS is connected.”
• Tap target ≥ 44 px. The mark is 20 px; the row stretches the click area to the full row height + width.

Code

One ChoiceList wrapper, three item primitives. The wrapper handles header, error, and the fieldset/legend semantics; the items handle their own marks and labels.

import { ChoiceList, Radio, Checkbox, RadioCard } from "@flatpay-dk/ui";

// Radio buttons
const [schedule, setSchedule] = useState("next");
<ChoiceList
  label="Payout schedule"
  subline="When the daily settlement should land."
  value={schedule}
  onValueChange={setSchedule}
>
  <Radio value="same" title="Same day" help="Available before 18:00 CET on weekdays." />
  <Radio value="next" title="Next business day" help="Lands by 09:00 the morning after." />
  <Radio value="weekly" title="Weekly" help="Bundled into one transfer every Monday." />
</ChoiceList>

// Checkboxes (multi-select)
const [options, setOptions] = useState(["vat", "policy"]);
<ChoiceList
  label="Receipt options"
  subline="What to include on customer-facing receipts."
  value={options}
  onValueChange={setOptions}
  type="checkbox"
>
  <Checkbox value="vat" title="Include VAT breakdown" />
  <Checkbox value="lines" title="Include itemised lines" />
  <Checkbox value="policy" title="Include refund policy" />
</ChoiceList>

// Radio cards (richer per-option content)
<ChoiceList
  label="Repayment plan"
  subline="Pick the plan that fits your daily revenue."
  value={plan}
  onValueChange={setPlan}
  orientation="horizontal"
>
  <RadioCard
    value="17"
    title="17% of daily sales"
    supporting="about 7 months to complete repayments"
    meta="75.000 kr service fee"
  />
  <RadioCard value="15" title="15% of daily sales" supporting="…" meta="…" />
  <RadioCard value="12" title="12% of daily sales" supporting="…" meta="…" />
</ChoiceList>

// Error state
<ChoiceList
  label="Pickup or delivery"
  value={method}
  onValueChange={setMethod}
  error="Choose pickup or delivery to continue."
>
  <Radio value="pickup" title="Pickup" />
  <Radio value="delivery" title="Delivery" />
</ChoiceList>

Best practices

Choice lists carry a lot of forms. Small habits compound into predictable, scannable surfaces.

Props

ChoiceList

Related