Components menu
  2. components
  3. forms
  4. choice list

Choice list

A choice list lets you create a list of grouped radio buttons or checkboxes. Use this component if you need to group together a related list of interactive choices.

Examples

Allows merchants to select one option from a list.

  • Make sure all options are an either/or choice.
Drag to resize example

Props

allowMultiple
boolean
Allow merchants to select multiple options at once
choicesRequired
Choice[]
Collection of choices
error
string | ReactElement | (string | ReactElement)[]
Display an error message
name
string
Name for form input
selectedRequired
string[]
Collection of selected choices
title
string
Label for list of choices
titleHidden
boolean
Toggles display of the title
onChange
(selected: string[], name: string) => void
Callback when the selected choices change

Accessibility

The choice list component uses the accessibility features of the checkbox and radio button components.

Single choice list

Allows merchants to select one option from a list.

  • Make sure all options are an either/or choice.

Single choice list for Android

Multi-choice list

Allows merchants to select multiple options from a list.

  • Avoid options that are an either/or choice.

Multi choice list for Android

Accessibility

See Material Design and development documentation about accessibility for Android:

Single choice list

Allows merchants to select one option from a list.

  • Make sure all options are an either/or choice.

Single choice list for iOS

Multi-choice list

Allows merchants to select multiple options from a list.

  • Avoid options that are an either/or choice.

Multi choice list for iOS

Accessibility

See Apple’s Human Interface Guidelines and API documentation about accessibility for iOS:

Best practices

Choice lists should:

  • Include a title that tells merchants what to do or explains the available options
  • Label options clearly based on what the option will do
  • Avoid mutually exclusive options when allowing multiple selection

Content guidelines

List titles

List titles should:

  • Help merchants understand how the items in the list are grouped together, or should explain what kind of choice merchants are making

  • Pick a shipping method

  • Pick one

  • Be concise and scannable:
    • Use simple, clear language that can be read at a glance
    • Keep list titles to a single sentence
    • It the title introduces the list, it should end with a colon
    • Should be written in sentence case

  • Shipping options

  • Shipping Options

  • Not use colons

Do

If the customer abandons their checkout, send them an email reminder to complete their order



Don’t

If the customer abandons their checkout, send them an email reminder to complete their order:



List choices

Every item in a choice list should:

  • Start with a capital letter

Do

  • Option 1
  • Option 2
  • Option 3

Don’t

  • option 1
  • option 2
  • option 3
  • Not use commas or semicolons at the end of each line

Do

  • Red
  • Yellow
  • Blue

Don’t

  • Red;
  • Yellow;
  • Blue.
  • Be written in sentence case (the first word capitalized, the rest lowercase)

Do

  • Item one
  • Item two
  • Item three

Don’t

  • Item One
  • Item Two
  • Item Three

Helper text and descriptions

If your list contains helper text, only the description below the list item should contain punctuation.