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 `id`s to your app. > Tip: > If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.

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;

picker

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.

PublicPickerApi

Returns: Promise<PickerInstance>

Params:

options: PickerOptions

export type PublicPickerApi = ( options: PickerOptions, ) => Promise<PickerInstance>;

PickerOptions

headers

The data headers for the picker. These are used to display the table headers in the picker modal.

heading

The heading of the picker. This is displayed in the title of the picker modal.

items

The items to display in the picker. These are used to display the rows in the picker modal.

multiple

Whether to allow selecting multiple items of a specific type or not. If a number is provided, then limit the selections to a maximum of that number of items.

Header

content

The content to display in the table column header.

type

The type of data to display in the column. The type is used to format the data in the column. If the type is 'number', the data in the column will be right-aligned, this should be used when referencing currency or numeric values. If the type is 'string', the data in the column will be left-aligned.

PickerItem

badges

The badges to display in the first column of the row. These are used to display additional information about the item, such as progress of an action or tone indicating the status of that item.

data

The additional content to display in the second and third columns of the row, if provided.

disabled

Whether the item is disabled or not. If the item is disabled, it cannot be selected.

heading

The primary content to display in the first column of the row.

id

selected

Whether the item is selected or not when the picker is opened. The user may deselect the item if it is preselected.

thumbnail

The thumbnail to display at the start of the row. This is used to display an image or icon for the item.

Badge

content

progress

tone

Progress

'incomplete' | 'partiallyComplete' | 'complete'

Tone

'info' | 'success' | 'warning' | 'critical'

DataPoint

string | number | undefined

PickerInstance

selected

A Promise that resolves with the selected item IDs when the user presses the "Select" button in the picker.

Related

• Picker

Examples

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 `id`s to your app. > Tip: > If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.

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.

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;

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;

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

const picker = await shopify.picker({
  heading: 'Limited selectable items (up to 2)',
  multiple: 2,
  headers: [{content: 'Main heading'}],
  items: [
    {
      id: '1',
      heading: 'Item 1',
    },
    {
      id: '2',
      heading: 'Item 2',
    },
    {
      id: '3',
      heading: 'Item 3',
    },
  ],
});

const selected = await picker.selected;

const picker = await shopify.picker({
  heading: 'Limited selectable items (up to 2)',
  multiple: 2,
  headers: [{content: 'Main heading'}],
  items: [
    {
      id: '1',
      heading: 'Item 1',
    },
    {
      id: '2',
      heading: 'Item 2',
    },
    {
      id: '3',
      heading: 'Item 3',
    },
  ],
});

const selected = await picker.selected;

Setting an unlimited number of selectable items.

const picker = await shopify.picker({
  heading: 'Unlimited selectable items',
  multiple: true,
  headers: [{content: 'Main heading'}],
  items: [
    {
      id: '1',
      heading: 'Item 1',
    },
    {
      id: '2',
      heading: 'Item 2',
    },
    {
      id: '3',
      heading: 'Item 3',
    },
  ],
});

const selected = await picker.selected;

const picker = await shopify.picker({
  heading: 'Unlimited selectable items',
  multiple: true,
  headers: [{content: 'Main heading'}],
  items: [
    {
      id: '1',
      heading: 'Item 1',
    },
    {
      id: '2',
      heading: 'Item 2',
    },
    {
      id: '3',
      heading: 'Item 3',
    },
  ],
});

const selected = await picker.selected;

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

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

const selected = await picker.selected;

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

const selected = await picker.selected;

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

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

const selected = await picker.selected;

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

const selected = await picker.selected;