Skip to main content

Picker API

Requires an admin UI block, action, or print extension.

The Picker API lets merchants search for and select items from your app-specific data, such as product reviews, email templates, or subscription options. Use this API to build custom selection dialogs with your own data structure, badges, and thumbnails. The picker returns the IDs of selected items.

Tip

If you need to pick Shopify products, variants, or collections, use the Resource Picker API instead.

  • App data selection: Let merchants select items from your app's own data, such as reviews, email templates, or subscription options. To offer Shopify data that the Resource Picker API doesn't cover, fetch it in your extension and map it into items.
  • Multi-select: Build interfaces that allow selecting multiple resources at once.
  • Searchable selection: Let merchants find items by searching the text and numbers in each item's heading, data columns, and badges.
  • Workflow integration: Integrate resource pickers into configuration workflows.

The picker function opens a custom selection dialog with your app-specific data. It accepts configuration options to define the picker's heading, items, headers, and selection behavior. It returns a Promise that resolves to a Picker object with a selected property for accessing the merchant's selection.

Anchor to options
options
required

Promise<>
Examples

jsx

import {render} from 'preact';
import {useState} from 'preact/hooks';

export default async () => {
render(<Extension />, document.body);
};

function Extension() {
const [selected, setSelected] = useState(null);

const handlePickTemplate = async () => {
const pickerInstance = 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: ['Russell Winfield', '5'],
badges: [
{content: 'Published', tone: 'success'},
{content: 'New feature'},
],
selected: true,
},
{
id: '3',
heading: 'Promo header, 2 column',
data: ['Russel Winfield', '10'],
badges: [{content: 'Published', tone: 'success'}],
},
],
});

const result = await pickerInstance.selected;
setSelected(result);
};

return (
<s-admin-block heading="Template Selector">
<s-button onClick={handlePickTemplate}>Choose Template</s-button>
{selected && selected.length > 0 && (
<s-text>Selected template: {selected[0]}</s-text>
)}
</s-admin-block>
);
}

Preview

Build a custom picker for email templates with multiple columns and status badges. This example shows defining column headers, populating items with searchable data fields, adding visual status indicators, and handling the selection promise. Use this pattern for app-specific resources like templates, product reviews, or subscription options where you need custom data structures beyond standard Shopify resources.

  • Handle undefined return on cancellation: When merchants cancel or close the picker, it returns undefined rather than an empty array. Check for undefined explicitly to distinguish cancellation from empty selection.
  • Disable items to prevent modification: Set disabled: true and selected: true on an item to show it as preselected and stop merchants from toggling it. The bulk selection checkbox still clears every selected item, including disabled ones. If your app needs an item to stay selected, then check for its ID in the returned selection.

  • The Picker API only supports app-specific data. It can't display Shopify resources like products or variants. Use Resource Picker API for Shopify resources.
  • Picker items don't support hierarchical or nested structures. All items appear in a flat list.
  • The picker can't be customized with additional filters, search operators, or sorting beyond what merchants type in the search field.

Was this page helpful?