---
title: Picker
description: |-
  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 extension.

  > Tip:
  > If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.
api_version: 2025-10
api_name: admin-extensions
source_url:
  html: https://shopify.dev/docs/api/admin-extensions/latest/api/picker
  md: https://shopify.dev/docs/api/admin-extensions/latest/api/picker.md
---

# Picker

Requires an Admin [block](https://shopify.dev/docs/api/admin-extensions/2025-10extension-targets#block-locations), [action](https://shopify.dev/docs/api/admin-extensions/2025-10extension-targets#action-locations), or [print](https://shopify.dev/docs/api/admin-extensions/2025-10extension-targets#print-locations) extension.

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 extension.

Tip

If you are picking products, product variants, or collections, you should use the [Resource Picker](resource-picker) API instead.

## picker([options](#picker-propertydetail-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.

### Parameters

* options

  PickerOptions

  required

### Returns

* Promise\<Picker>

### PickerOptions

* headers

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

  ```ts
  Header[]
  ```

* heading

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

  ```ts
  string
  ```

* items

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

  ```ts
  Item[]
  ```

* multiple

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

  ```ts
  boolean | number
  ```

```ts
interface PickerOptions {
  /**
   * The heading of the picker. This is displayed in the title of the picker modal.
   */
  heading: string;
  /**
   * The data headers for the picker. These are used to display the table headers in the picker modal.
   */
  multiple?: boolean | number;
  /**
   * The items to display in the picker. These are used to display the rows in the picker modal.
   */
  items: Item[];
  /**
   * The data headers for the picker. These are used to display the table headers in the picker modal.
   */
  headers?: Header[];
}
```

### Header

* content

  The content to display in the table column header.

  ```ts
  string
  ```

* 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.

  ```ts
  'string' | 'number'
  ```

```ts
interface Header {
  /**
   * The content to display in the table column header.
   */
  content?: string;
  /**
   * 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.
   * @defaultValue 'string'
   */
  type?: 'string' | 'number';
}
```

### Item

* 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.

  ```ts
  PickerBadge[]
  ```

* data

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

  ```ts
  DataPoint[]
  ```

* disabled

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

  ```ts
  boolean
  ```

* heading

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

  ```ts
  string
  ```

* id

  The unique identifier of the item. This will be returned by the picker if selected.

  ```ts
  string
  ```

* selected

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

  ```ts
  boolean
  ```

* thumbnail

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

  ```ts
  { url: string; }
  ```

```ts
interface Item {
  /**
   * The unique identifier of the item. This will be returned by the picker if selected.
   */
  id: string;
  /**
   * The primary content to display in the first column of the row.
   */
  heading: string;
  /**
   * The additional content to display in the second and third columns of the row, if provided.
   */
  data?: DataPoint[];
  /**
   * Whether the item is disabled or not. If the item is disabled, it cannot be selected.
   * @defaultValue false
   */
  disabled?: boolean;
  /**
   * Whether the item is selected or not when the picker is opened. The user may deselect the item if it is preselected.
   */
  selected?: boolean;
  /**
   * 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.
   */
  badges?: PickerBadge[];
  /**
   * The thumbnail to display at the start of the row. This is used to display an image or icon for the item.
   */
  thumbnail?: {url: string};
}
```

### PickerBadge

* content

  ```ts
  string
  ```

* progress

  ```ts
  Progress
  ```

* tone

  ```ts
  Tone
  ```

```ts
interface PickerBadge {
  content: string;
  tone?: Tone;
  progress?: Progress;
}
```

### Progress

```ts
'incomplete' | 'partiallyComplete' | 'complete'
```

### Tone

```ts
'info' | 'success' | 'warning' | 'critical'
```

### DataPoint

```ts
string | number | undefined
```

### Picker

* selected

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

  ```ts
  Promise<string[] | undefined>
  ```

```ts
interface Picker {
  /**
   * A Promise that resolves with the selected item IDs when the user presses the "Select" button in the picker.
   */
  selected: Promise<string[] | undefined>;
}
```

### Examples

* #### Picker

  ##### js

  ```js
  const {picker} = useApi(TARGET);

  const pickerInstance = await picker({
    heading: 'Select a template',
    multiple: false,
    headers: [
      {title: 'Templates'},
      {title: 'Created by'},
      {title: '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 selected = await pickerInstance.selected;
  ```

## Preview

![](https://shopify.dev/images/templated-apis-screenshots/admin-extensions/2025-10/picker.png)

## Examples

Pickers with different options

Simple 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.

Limited selectable items

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

Unlimited selectable items

Setting an unlimited number of selectable items.

Preselected items

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

Disabled items

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

### Examples

* #### Simple picker

  ##### Description

  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.

  ##### Default

  ```js
  const pickerInstance = await picker({
    heading: 'Select an item',
    headers: [{title: 'Main heading'}],
    items: [
      {
        id: '1',
        heading: 'Item 1',
      },
      {
        id: '2',
        heading: 'Item 2',
      },
    ],
  });

  const selected = await pickerInstance.selected;
  ```

* #### Limited selectable items

  ##### Description

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

  ##### Default

  ```js
  const pickerInstance = await picker({
    heading: 'Select items (up to 2)',
    multiple: 2,
    headers: [{title: 'Main heading'}],
    items: [
      {
        id: '1',
        heading: 'Item 1',
      },
      {
        id: '2',
        heading: 'Item 2',
      },
      {
        id: '3',
        heading: 'Item 3',
      },
    ],
  });

  const selected = await pickerInstance.selected;
  ```

* #### Unlimited selectable items

  ##### Description

  Setting an unlimited number of selectable items.

  ##### Default

  ```js
  const pickerInstance = await picker({
    heading: 'Select items',
    multiple: true,
    headers: [{title: 'Main heading'}],
    items: [
      {
        id: '1',
        heading: 'Item 1',
      },
      {
        id: '2',
        heading: 'Item 2',
      },
      {
        id: '3',
        heading: 'Item 3',
      },
    ],
  });

  const selected = await pickerInstance.selected;
  ```

* #### Preselected items

  ##### Description

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

  ##### Default

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

  const selected = await pickerInstance.selected;
  ```

* #### Disabled items

  ##### Description

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

  ##### Default

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

  const selected = await pickerInstance.selected;
  ```

## Related

[![](https://shopify.dev/images/icons/32/pickaxe-3.png)![](https://shopify.dev/images/icons/32/pickaxe-3-dark.png)](https://shopify.dev/docs/api/admin-extensions/latest/api/resource-picker)

[APIsResource Picker](https://shopify.dev/docs/api/admin-extensions/latest/api/resource-picker)