Skip to main content

Picker

The Picker API provides a search-based interface to help users find and select one or more resources that you provide, such as product reviews, email templates, or subscription options, and then returns the selected resource ids to your app.

Tip

If you are picking products, product variants, or collections, you should use the Resource Picker API instead.

Anchor to picker
picker(
options
)

The picker API is a function that accepts an options argument for configuration and returns a Promise that resolves to the picker instance once the picker modal is opened.

Anchor to picker-parametersParameters

Anchor to options
options
required

Anchor to picker-returnsReturns

Promise<>
Was this section helpful?

Picker

const picker = await shopify.picker({
heading: 'Select a template',
multiple: false,
headers: [
{content: 'Templates'},
{content: 'Created by'},
{content: 'Times used', type: 'number'},
],
items: [
{
id: '1',
heading: 'Full width, 1 column',
data: ['Karine Ruby', '0'],
badges: [{content: 'Draft', tone: 'info'}, {content: 'Marketing'}],
},
{
id: '2',
heading: 'Large graphic, 3 column',
data: ['Charlie Mitchell', '5'],
badges: [
{content: 'Published', tone: 'success'},
{content: 'New feature'},
],
selected: true,
},
{
id: '3',
heading: 'Promo header, 2 column',
data: ['Russell Winfield', '10'],
badges: [{content: 'Published', tone: 'success'}],
},
],
});

const selected = await picker.selected;

Preview

Anchor to examplesExamples

Pickers with different options

Anchor to example-simple-pickerSimple picker

Minimal required fields picker configuration.

If you don't provide the required options (heading and items), the picker will not open and an error will be logged.

Anchor to example-limited-selectable-itemsLimited selectable items

Setting a specific number of selectable items. In this example, the user can select up to 2 items.

Anchor to example-unlimited-selectable-itemsUnlimited selectable items

Setting an unlimited number of selectable items.

Anchor to example-preselected-itemsPreselected items

Providing preselected items in the picker. These will be selected when the picker opens but can be deselected by the user.

Anchor to example-disabled-itemsDisabled items

Providing disabled items in the picker. These will be disabled and cannot be selected by the user.

Was this section helpful?

Simple picker

const picker = await shopify.picker({
heading: 'Simple picker configuration',
items: [
{
id: '1',
heading: 'Item 1',
},
{
id: '2',
heading: 'Item 2',
},
],
});

const selected = await picker.selected;

Anchor to relatedRelated

APIsPicker