Choose a version:

Resource Picker API

Requires an admin UI block, action, or print 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 instead.

Anchor to Use casesUse 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.

Anchor to PropertiesProperties

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.

Anchor to type 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.
Anchor to action 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.
Anchor to filter filter: 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.
Anchor to multiple 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.
Anchor to query 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 for the query format. For most use cases, use filter.query instead, which filters results without exposing the query to merchants.
Anchor to selectionIds selectionIds [] 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.
```
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.
```
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.
```
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"`).
```
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.
```
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`).
```
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.
```
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`).
```
string
```

Anchor to ResourcePicker return payloadResourcePicker 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>

Anchor to SelectPayload

SelectPayload

<Type>

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

);

}

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.

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

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

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

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

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

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

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

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

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

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>
  );
}

Anchor to Best practicesBest 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.

Anchor to LimitationsLimitations

Only products, variants, and collections are supported. Other resource types like customers, orders, or locations can't be selected. Use the 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.

Was this page helpful?