---
title: ChoiceList
description: >-
  Use choice lists to present a list of choices where buyers can make a single
  selection or multiple selections.
api_version: 2025-01
api_name: checkout-ui-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-01/components/forms/choicelist
  md: >-
    https://shopify.dev/docs/api/checkout-ui-extensions/2025-01/components/forms/choicelist.md
---

# Choice​List

Use choice lists to present a list of choices where buyers can make a single selection or multiple selections.

## ChoiceListProps

* name

  string

  required

  A unique identifier for the field in the closest `Form` component.

* onChange

  (value: T) => void

  required

  A callback that is run whenever the choice list is changed. This callback is called with a string or array of strings indicating the ids of choices that should now be selected. This component is [controlled](https://reactjs.org/docs/forms.html#controlled-components), so you must store this value in state and reflect it back in the `value` prop.

* value

  T

  required

  A `string` or `string[]` indicating the ids of selected choices. **When a string is set, choices render as radios. When a string array is set, choices render as checkboxes**.

* variant

  'base' | 'group'

  Default: 'base'

  Toggle between `base` and `group` look.

  Check the [best practices](#best-practices) to learn more about the variants.

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/checkout-ui-extensions/2025-01/choicelist-default.png)

## Best Practices

### Content

* Include a title that either tells customers what to do or explains their available options.

* Label options clearly based on what the option will do.

* Avoid options that contradict each other when you’re allowing for multiple selections.

### Types of choices

![A screenshot of two examples for base and group variants](https://shopify.dev/images/landing-pages/templated-apis/checkout-ui-extensions/ui-components/choicelist-bp-choicetypes.png)

* The `base` variant is suitable for straightforward options, such as binary choices like 'yes' or 'no' answers. For simple options that require minimal visual emphasis, the base variant is the recommended choice.
* The `group` variant provides increased emphasis on choices through the use of colors, borders, and dividers. If the goal is to draw attention to the available options, the group variant is the ideal choice.

### Flexibility vs. cohesive experience

* The `base` variant offers the flexibility to compose ChoiceLists with custom layouts, allowing for greater design composition possibilities.
* Given the high level of flexibility offered by the `base` variant, prioritizing accessibility in the implementation is crucial. It is recommended to avoid using buttons or pressable components within the choices.
* The `group` variant adheres to a defined structure and provides excellent adaptability to align with the merchant’s brand. It is the ideal choice when strong cohesion with the merchant’s branding is required. Additionally, depending on the placement of the `ChoiceList`, Checkout will automatically update its appearance to seamlessly adapt to the surface it is on.

### Using details

![A screenshot of an example of using details](https://shopify.dev/images/landing-pages/templated-apis/checkout-ui-extensions/ui-components/choicelist-bp-details.png)

* The `details` area should be used only when additional input is required from the customer, specifically related to the choice they have made.
* If the `details` area contains lengthy content, consider placing it outside of the `ChoiceList` to ensure that customers can easily digest the information.

### Long lists of options

* When faced with a considerable number of options, customers may feel overwhelmed, and it can consume valuable interface space. To address this, consider utilizing components like the [Select](https://shopify.dev/docs/api/checkout-ui-extensions/components/forms/select) component to condense options, or employ the [Disclosure](https://shopify.dev/docs/api/checkout-ui-extensions/components/interactive/disclosure) component to progressively reveal more choices upon customer request. Strategies such as paging, filtering, and searching can be employed to enhance usability.

### Clickable rows

* If an entire row needs to be clickable, utilize the `group` variant, as it is specifically designed to enable clickable rows. In this scenario, the base variant may not provide the desired functionality, as only its content elements can be clicked, not the entire row. Attempting to use buttons or pressables to make an entire row clickable could lead to accessibility issues.

## Examples

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/checkout-ui-extensions/2025-01/choicelist-survey.png)

## Related

[Component - Choice](choice)

[Component - Checkbox](checkbox)