---
title: Resource Picker API
description: >-
  The Resource Picker API lets merchants search for and select products,
  collections, or product variants. Use this API when your extension needs
  merchants to choose Shopify resources to work with.
api_version: 2026-01
api_name: admin-extensions
source_url:
  html: >-
    https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/resource-picker-api
  md: >-
    https://shopify.dev/docs/api/admin-extensions/latest/target-apis/utility-apis/resource-picker-api.md
---

# Resource Picker API

**Requires an admin UI \[block, action, or print]\(/docs/api/admin-extensions/2026-01#building-your-extension) extension.:**

The Resource Picker API lets merchants search for and select products, collections, or product variants. Use this API when your extension needs merchants to choose Shopify resources to work with. The resource picker returns detailed resource information including IDs, titles, images, and metadata.

**Tip:**

If you need to pick app-specific resources like product reviews, email templates, or subscription options, use the [Picker API](https://shopify.dev/docs/api/admin-extensions/2026-01/target-apis/utility-apis/picker-api) instead.

### Use cases

* **Resource selection:** Display resource picker interfaces for selecting Shopify resources.
* **Product selection:** Enable product selection in bundle or collection configuration workflows.
* **Customer selection:** Select customers for targeting or segmentation purposes.
* **Bulk selection:** Support bulk resource selection for batch operations.

### Properties

The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. Access the following properties on the `ResourcePickerOptions` object to configure the resource picker's appearance and functionality.

* **type**

  **'product' | 'variant' | 'collection'**

  **required**

  The type of Shopify resource to select: `'product'` for products, `'variant'` for specific product variants, or `'collection'` for collections. This determines what appears in the picker and what data structure is returned.

* **action**

  **'add' | 'select'**

  **Default: 'add'**

  The action verb that appears in the picker's title and primary button. Use `'add'` for actions that add new items (for example, "Add products") or `'select'` for choosing existing items (for example, "Select products"). This helps merchants understand the picker's purpose.

* **filter**

  **Filters**

  Filtering options that control which resources appear in the picker. Use filters to restrict resources by publication status, include or exclude variants, or apply custom search criteria. This helps merchants find relevant items faster.

* **multiple**

  **boolean | number**

  **Default: false**

  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, `5` allows up to five items). When `type` is `'product'`, merchants can still select multiple variants from a single product even if `multiple` is `false`.

* **query**

  **string**

  **Default: ''**

  An initial search query that appears in the picker's search bar when it opens. Merchants can see and edit this query. See [search syntax](https://shopify.dev/docs/api/usage/search-syntax) for the query format. For most use cases, use `filter.query` instead, which filters results without exposing the query to merchants.

* **selectionIds**

  **BaseResource\[]**

  **Default: \[]**

  Resources that should be preselected when the picker opens. Pass an array of resource objects with IDs (and optional variant IDs) to show which items are already selected. Merchants can deselect these preselected items. Use this to show current selections or default choices.

### Filters

Filter options that control which resources appear in the resource picker. Use filters to restrict the available resources based on publication status, resource type, or custom search criteria.

* archived

  Whether to include archived products in the picker. When \`false\`, archived products are hidden. When \`undefined\`, archived products appear with an archived badge. Only applies when \`type\` is \`'product'\`. Use this to prevent selecting discontinued products.

  ```ts
  boolean | undefined
  ```

* draft

  Whether to include draft products in the picker. When \`false\`, draft products are hidden. When \`undefined\`, draft products appear with a draft badge. Only applies when \`type\` is \`'product'\`. Use this to prevent selecting products that aren't ready for use.

  ```ts
  boolean | undefined
  ```

* hidden

  Whether to include products that aren't published on any sales channels. When \`false\`, only products published to at least one sales channel appear in the picker. Use this to ensure merchants only select products that customers can purchase.

  ```ts
  boolean
  ```

* query

  A GraphQL search query that filters the available resources without showing the query in the picker's search bar. Merchants won't see or edit this filter. See \[search syntax]\(/docs/api/usage/search-syntax) for the query format. Use this to programmatically restrict resources based on attributes like tags, vendor, or product type (for example, \`"tag:featured"\` or \`"vendor:Acme"\`).

  ```ts
  string
  ```

* variants

  Whether to show product variants in the picker. When \`false\`, merchants can only select products, not individual variants. Only applies when \`type\` is \`'product'\`. Use this to simplify selection when you only need product-level data.

  ```ts
  boolean
  ```

### BaseResource

A resource structure that can optionally include associated variants. Use this type for specifying preselected items in the resource picker when you need to include variant selections.

* id

  The resource identifier in GraphQL global ID format (for example, \`gid://shopify/Product/123\`).

  ```ts
  string
  ```

* variants

  An array of variant resources to preselect along with the main resource. Only applicable when the main resource is a product that has variants you want to preselect.

  ```ts
  Resource[]
  ```

### Resource

The base resource structure with a unique identifier.

* id

  The resource identifier in GraphQL global ID format (for example, \`gid://shopify/Product/123\`).

  ```ts
  string
  ```

### Resource​Picker return payload

The resource picker returns an array of selected resources when the merchant confirms their selection, or `undefined` if they cancel. The resource structure in the array varies based on the `type` option: products include variants and images, collections include rule sets, and variants include pricing and inventory data.

**`SelectPayload<Type>`**

### SelectPayload

* **SelectPayload<Type>**

Examples

## Preview

![Open the product resource picker to select items from the store catalog. This example invokes \`shopify.resourcePicker\` with \`type: 'product'\`, handles the async selection, and displays the count of selected products. When merchants confirm their selection, the resource picker returns an array of product objects with GIDs, titles, and handles for use in your extension.](https://shopify.dev/assets/assets/images/apps/tools/app-bridge-resource-picker-DXcLV_Ca.png)

### Examples

* ####

  ##### Description

  Open the product resource picker to select items from the store catalog. This example invokes \`shopify.resourcePicker\` with \`type: "product"\`, handles the async selection, and displays the count of selected products. When merchants confirm their selection, the resource picker returns an array of product objects with GIDs, titles, and handles for use in your extension.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({type: 'product'});
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Filter the picker to show only published products using the \`filter\` option with \`published\_status: "published"\`. This example shows restricting the picker to live, customer-visible products. Use this for promotional campaigns, product recommendations, or any feature that should only work with active inventory, preventing accidental selection of draft or archived products.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        query: 'published_status:published',
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Published Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Limit selection to a maximum of five products by setting \`multiple: 5\`. This example shows restricting how many products merchants can choose. This is useful for bundle builders with item limits, featured product sections with fixed display slots, or promotional campaigns with maximum product counts. The resource picker automatically prevents selection beyond the limit.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        multiple: 5,
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Open the resource picker with products already selected by passing GIDs to the \`selectionIds\` option. This example shows pre-populating the resource picker with current selections for edit workflows. Use this for showing what products are already in a bundle, collection, or promotional set. Merchants can see current selections and modify them by adding or removing products before confirming.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        selectionIds: [
          'gid://shopify/Product/123',
          'gid://shopify/Product/456',
        ],
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Select collections instead of individual products by setting \`type: "collection"\`. This example shows switching the resource picker to collection mode for choosing product groupings. This is useful for homepage featured collection carousels, navigation menu builders, bulk collection operations, or promotional campaigns targeting entire product categories rather than individual items.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({type: 'collection'});
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Collections</s-button>
        {selected && <s-text>{selected.length} collections selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Allow unlimited product selection by setting \`multiple: true\` without a numeric limit. This example shows enabling flexible multi-selection where merchants control the quantity. Use this for mass product taggers, bulk inventory tools, category managers, or export utilities where selection count depends on merchant needs without artificial constraints.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        multiple: true,
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Select specific product variants instead of entire products by setting \`type: "variant"\`. This example shows switching to variant-level selection for choosing individual SKUs. Use this for inventory transfer tools, variant-specific promotions, wholesale pricing sheets, or shipment builders where you need granular control over size, color, and individual SKU tracking.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({type: 'variant'});
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Variants</s-button>
        {selected && <s-text>{selected.length} variants selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Customize the resource picker button text by setting the \`action\` option to "add" or "select". This example shows changing the action verb to provide workflow context. "Add" suggests appending to an existing list, while "select" implies choosing for a specific purpose or replacing selections. This subtle language difference improves clarity for different workflow contexts.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        action: 'add',
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

* ####

  ##### Description

  Start the resource picker with a pre-filled search query by passing the \`query\` option. This example shows initializing the picker with a search term already entered. This is helpful when you know what merchants are likely looking for, such as products from a specific vendor, tag, or product type. Merchants can modify the query, but starting with relevant results saves time in large catalogs.

  ##### jsx

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

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

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

    const handlePick = async () => {
      const result = await shopify.resourcePicker({
        type: 'product',
        query: 'shirt',
      });
      setSelected(result);
    };

    return (
      <s-admin-block heading="Resource Picker">
        <s-button onClick={handlePick}>Select Products</s-button>
        {selected && <s-text>{selected.length} products selected</s-text>}
      </s-admin-block>
    );
  }
  ```

***

## Best practices

* **Filter query runs server-side:** The `query` property in filters isn't visible to merchants and runs as a GraphQL search query. Use it to programmatically restrict results (for example, `vendor:Acme`) without exposing the filter logic.
* **Handle undefined return on cancellation:** When merchants close the picker without selecting, it returns `undefined` rather than an empty array. Check for `undefined` explicitly.

***

## Limitations

* Only products, variants, and collections are supported. Other resource types like customers, orders, or locations can't be selected. Use the [Picker API](https://shopify.dev/docs/api/admin-extensions/2026-01/target-apis/utility-apis/picker-api) for custom resources.
* Product selection with `multiple: false` doesn't prevent multi-variant selection from the same product. Merchants can select multiple variants from a single product even when `multiple: false`.
* Filter options are limited to predefined fields (`hidden`, `variants`, `draft`, `archived`, `query`). Custom filter criteria beyond these aren't supported.
* Returned data structure varies by resource type. Products include a `variants` array, variants include `price` and `inventoryQuantity`, and collections include `ruleSet`.

***