SChoiceList <s-choice-list>

A group of radio buttons or checkboxes for picking one or several options. SChoiceList is the typed Vue 3 wrapper for Shopify's Polaris <s-choice-list> web component.

import { SChoiceList } from 'polaris-vue-elements'

Best practices

• Match the selection mode to the options. Keep single selection for options that exclude each other, like payment methods or shipping speeds, and set multiple when merchants can pick more than one.
• Make choice labels describe the outcome. "Email notifications for new orders" says more than "Email". Keep labels short, but clear enough to stand on their own.
• Phrase the label as a question or statement. A title such as "Which shipping method?" or "Select notification preferences" tells merchants more than a vague word like "Options" or "Settings".
• Explain complex choices in the details slot. Add details to an individual SChoice when merchants need to understand what picking it implies.
• Make error messages specific. Tell merchants exactly what's missing, for example "Select at least one notification preference", instead of a generic "Required field".

<SChoiceList label="Which shipping method?">
  <SChoice value="standard">Standard shipping</SChoice>
  <SChoice value="express">
    Express shipping
    <template #details>
      <SText>Costs more, but orders arrive in 1–2 business days.</SText>
    </template>
  </SChoice>
</SChoiceList>

See Shopify's best practices for <s-choice-list> for the full guidance.

Example

EmailSMSPush notification

Selected: (none)

<script setup>
import { ref } from 'vue'
import { SChoiceList, SChoice } from 'polaris-vue-elements'

const value = ref([])
</script>

<template>
  <SChoiceList label="Notify me by" multiple v-model="value">
    <SChoice value="email">Email</SChoice>
    <SChoice value="sms">SMS</SChoice>
    <SChoice value="push">Push notification</SChoice>
  </SChoiceList>
  <p>Selected: {{ value.join(', ') }}</p>
</template>

v-model

v-model on <SChoiceList> binds to the values property and listens for the change DOM event.

<SChoiceList v-model="value" />

is equivalent to:

<SChoiceList :values="value" @change="value = $event.target.values" />

Props

Prop	Type	Description
details	any	Additional text to provide context or guidance for the field. This text is displayed along with the field and its label to offer more information or instructions to the user. This will also be exposed to screen reader users.
disabled	boolean	Whether the field is disabled, preventing any user interaction. When true, the disabled property on any child choices is ignored.
error	any	Indicate an error to the user. The field will be given a specific stylistic treatment to communicate problems that have to be resolved immediately.
label	any	Content to use as the field label.
labelAccessibilityVisibility	"visible" | "exclusive"	Changes the visibility of the component's label. - visible: the label is visible to all users. - exclusive: the label is visually hidden but remains in the accessibility tree.
multiple	boolean	Whether multiple choices can be selected.
name	string	An identifier for the field that is unique within the nearest containing form.
values	string[]	An array of the values of the selected options. This is a convenience prop for setting the selected prop on child options.

Events

Event	Type
change	Event
input	Event

Listen for these with @change-style listeners on <SChoiceList>.

Slots

Slot	Description
default	The choices a user can select from. Accepts choice components.