--- title: Picker API description: >- 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 api_version: 2026-01 api_name: admin-extensions source_url: html: >- https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api md: >- https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/picker-api.md --- # Picker API **Requires an admin UI \[block, action, or print]\(/docs/api/admin-extensions/2026-01#building-your-extension) 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](https://shopify.dev/docs/api/admin-extensions/2026-01/target-apis/utility-apis/resource-picker-api) instead. ### Use cases * **Resource selection:** Enable resource picker dialogs for selecting products, customers, or other resources. * **Multi-select:** Build interfaces that allow selecting multiple resources at once. * **Filtered selection:** Provide filtered resource selection with search and filtering capabilities. * **Workflow integration:** Integrate resource pickers into configuration workflows. ## picker(**[options](#picker-propertydetail-options)**​) 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. ### Parameters * **options** **PickerOptions** **required** ### Returns * **Promise\** ### PickerOptions The configuration options for the custom picker dialog. Define the picker's appearance, selection behavior, and data structure. * headers The column headers for the picker table. Define headers to label and organize the data columns displayed for each item. The header order determines the column layout. ```ts Header[] ``` * heading The heading displayed at the top of the picker modal. Use a clear, descriptive title that tells merchants what they're selecting. ```ts string ``` * items The list of items that merchants can select from. Each item appears as a row in the picker table. ```ts Item[] ``` * multiple The selection mode for the picker. Pass \`true\` to allow unlimited selections, \`false\` for single-item selection only, or a number to set a maximum selection limit (for example, \`3\` allows up to three items). ```ts boolean | number ``` ### Header The configuration for a table column header in the picker. Each header creates a labeled column that displays corresponding data from items. * content The label text displayed at the top of the table column. Use clear, concise labels that describe the data in that column (for example, "Price", "Status", "Last Updated"). ```ts string ``` * type The data type that controls column formatting and text alignment. Use \`'number'\` for currency, prices, or numeric values (displays right-aligned), or \`'string'\` for text content (displays left-aligned). ```ts 'string' | 'number' ``` ### Item An individual item that merchants can select in the picker. Each item appears as a row in the picker table. * badges Status or context badges displayed next to the heading in the first column. Use badges to highlight item state, completion status, or other important attributes (for example, "Draft", "Published", "Incomplete"). ```ts PickerBadge[] ``` * data Additional data displayed in subsequent columns after the heading. Each value appears in its own column, and the order must match the \`headers\` array. For example, if headers are \`\["Price", "Status"]\`, then data would be \`\[19.99, "Active"]\`. ```ts DataPoint[] ``` * disabled Whether the item can be selected. When \`true\`, the item is disabled and can't be selected. Disabled items appear grayed out and merchants can't choose them. Use this for items that are unavailable or don't meet selection criteria. ```ts boolean ``` * heading The primary text displayed in the first column. This is typically the item's name or title and is the most prominent text in the row. ```ts string ``` * id The unique identifier for this item. This ID is returned in the selection array when the merchant selects this item. Use an ID that helps you identify the item in your system (for example, template IDs, review IDs, or custom option keys). ```ts string ``` * selected Whether the item is preselected when the picker opens. When \`true\`, the item appears selected by default. Merchants can still deselect preselected items. Use this to show current selections or suggest default choices. ```ts boolean ``` * thumbnail A small preview image or icon displayed at the start of the row. Thumbnails help merchants visually identify items at a glance. Provide a URL to the image file. ```ts { url: string; } ``` ### PickerBadge A badge displayed next to an item in the picker to show status or progress. Use badges to highlight important item attributes or states that affect selection decisions. * content The text content of the badge. Keep this short and descriptive (for example, "Draft", "Active", "Incomplete"). ```ts string ``` * progress The progress indicator for the badge. Use this to show completion status for items that have progress states. ```ts Progress ``` * tone The visual tone indicating status or importance. Choose a tone that matches the badge's meaning. ```ts Tone ``` ### Progress The progress state for picker badges showing completion status. Use this to indicate how complete an item is: \`'incomplete'\` for not started, \`'partiallyComplete'\` for in progress, or \`'complete'\` for finished. ```ts 'incomplete' | 'partiallyComplete' | 'complete' ``` ### Tone The visual tone for picker badges indicating status or importance. Use different tones to communicate urgency or state: \`'info'\` for neutral information, \`'success'\` for positive states, \`'warning'\` for caution, or \`'critical'\` for urgent issues. ```ts 'info' | 'success' | 'warning' | 'critical' ``` ### DataPoint A single data point that can appear in a picker table cell. Can be text, a number, or undefined if the cell should be empty. ```ts string | number | undefined ``` ### Picker A handle returned when opening a picker dialog. Use this to access the merchant's selection after they confirm or cancel the picker. * selected A Promise that resolves with an array of selected item IDs when the merchant presses the \*\*Select\*\* button, or \`undefined\` if they cancel. Await this Promise to handle the selection result. ```ts Promise ``` Examples ## 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.](https://shopify.dev/assets/assets/images/api/admin-extensions/2025-10/picker-DqQDb5eA.png) ### Examples * #### ##### Description 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. ##### jsx ```tsx import {render} from 'preact'; import {useState} from 'preact/hooks'; export default async () => { render(, 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 ( Choose Template {selected && selected.length > 0 && ( Selected template: {selected[0]} )} ); } ``` * #### ##### Description Disable specific picker items to prevent selection while keeping them visible for context. This example shows setting \`disabled: true\` on individual items to mark them as non-selectable. This is useful for showing all available options while preventing selection of incompatible resources, templates currently being edited by others, or deprecated features that require upgrades. ##### jsx ```tsx import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const handlePick = async () => { await shopify.picker({ heading: 'Select items', items: [ {id: '1', heading: 'Available item'}, {id: '2', heading: 'Disabled item', disabled: true}, ], }); }; return ( Open Picker ); } ``` * #### ##### Description Limit selection to a maximum number of items by setting \`multiple: 2\` in the picker options. This example shows restricting selection to exactly 2 items. Use this when your feature has hard constraints, such as A/B test variants needing exactly two options, comparison views with fixed slots, or integration mappings that support a specific connection count. ##### jsx ```tsx import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const handlePick = async () => { await shopify.picker({ heading: 'Select 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'}, ], }); }; return ( Open Picker ); } ``` * #### ##### Description Open the picker with items already selected by setting \`selected: true\` on individual items. This example shows pre-marking items as selected when the picker opens. Use this for edit workflows where you need to show what resources are already associated with a configuration, such as automation rule triggers or notification recipients. Merchants can modify the selection before confirming. ##### jsx ```tsx import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const handlePick = async () => { await shopify.picker({ heading: 'Select items', items: [ {id: '1', heading: 'Item 1', selected: true}, {id: '2', heading: 'Item 2'}, ], }); }; return ( Open Picker ); } ``` * #### ##### Description Allow unlimited selection by setting \`multiple: true\` without a numeric limit. This example shows enabling flexible multi-selection where merchants control how many items to choose. This is useful for bulk operations, mass notification sending, export tools, or tag management where selection quantity depends on merchant needs without artificial constraints. ##### jsx ```tsx import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const handlePick = async () => { await shopify.picker({ heading: 'Select items', multiple: true, items: [ {id: '1', heading: 'Item 1'}, {id: '2', heading: 'Item 2'}, {id: '3', heading: 'Item 3'}, ], }); }; return ( Open Picker ); } ``` * #### ##### Description Populate the picker with data from the \[GraphQL Admin API]\(/docs/api/admin-graphql). This example fetches order data when the button is clicked, maps results to picker items, and opens the picker with the returned data. Use this pattern for Shopify data that isn't available through the Resource Picker API, such as orders, draft orders, or fulfillments. ##### jsx ```tsx import {render} from 'preact'; export default async () => { render(, document.body); }; function Extension() { const handlePick = async () => { const r = await fetch('shopify:admin/api/graphql.json', { method: 'POST', body: JSON.stringify({ query: `query GetOrders($first: Int!) { orders(first: $first) { edges { node { id name } } } }`, variables: {first: 10}, }), }); const {data} = await r.json(); await shopify.picker({ heading: 'Select orders', items: data.orders.edges.map((edge) => ({ id: edge.node.id, heading: edge.node.name, })), }); }; return ( Open Order Picker ); } ``` *** ## Best practices * **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:** Use the `disabled` property on items combined with `initialSelectionIds` to create preselected items that merchants can't deselect. *** ## Limitations * The Picker API only supports app-specific data. It can't display Shopify resources like products or variants. Use [Resource Picker API](https://shopify.dev/docs/api/admin-extensions/2026-01/target-apis/utility-apis/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. ***