Resource Picker API

The Resource Picker API lets merchants search for and select products, collections, or product variants. Use this API when your app 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

Product selection: Help users find and select products from the store catalog.
Collection selection: Allow users to pick collections for promotions, automations, or display.
Variant selection: Enable selection of specific product variants for targeted operations.
Permission-aware: Select resources that both the app and the user have permissions to access.

Anchor to InputsInputs

The ResourcePickerOptions object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items.

Anchor to type type ResourceType 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 title as the primary action of the resource picker. "Add" prompts merchants that they are appending to an existing list, while "select" they'll choose a resource for a specific purpose or replacing selections.
Anchor to filter filter: Filtering options that control which resources appear in the resourcepicker. 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: Whether to allow selecting multiple items of a specific type. If a number is provided, limit selections to that maximum. When type is 'product', merchants can still select multiple variants from a single product even when multiple is false.
Anchor to query query string Default: '': Initial GraphQL search query for filtering resources available in the resource picker. See search syntax for more information. This is displayed in the search bar when the picker is opened and can be edited by users. For most use cases, you should use the filter.query option instead which doesn't show the query in the UI.
Anchor to selectionIds selectionIds [] Default: []: Resources that should be preselected when the picker is opened. Use this for edit workflows to show what products are already in a bundle, collection, or promotional set. Merchants can see current selections and modify them before confirming.

Filters

archived
Whether to show [archived products](https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability). Only applies to the Product resource type picker. Setting this to undefined will show a badge on draft products.
```
boolean | undefined
```
draft
Whether to show [draft products](https://help.shopify.com/en/manual/products/details?shpxid=70af7d87-E0F2-4973-8B09-B972AAF0ADFD#product-availability). Only applies to the Product resource type picker. Setting this to undefined will show a badge on draft products.
```
boolean | undefined
```
hidden
Whether to show hidden resources, referring to products that are not published on any sales channels.
```
boolean
```
query
GraphQL initial search query for filtering resources available in the picker. See [search syntax](https://shopify.dev/docs/api/usage/search-syntax) for more information. This query is not visible to merchants and runs server-side. Use it to programmatically restrict results (for example, `vendor:Acme`) without exposing the filter logic.
```
string
```
variants
Whether to show product variants. Only applies to the Product resource type picker.
```
boolean
```

BaseResource

id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
variants
```
Resource[]
```

Resource

id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```

Anchor to Return payloadReturn 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.

Anchor to when type is "collection": when type is "collection": []
Anchor to when type is "product": when type is "product": []
Anchor to when type is "variant": when type is "variant": []

Collection

availablePublicationCount
```
number
```
description
```
string
```
descriptionHtml
```
string
```
handle
```
string
```
id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
image
```
Image | null
```
productsAutomaticallySortedCount
```
number
```
productsCount
```
number
```
productsManuallySortedCount
```
number
```
publicationCount
```
number
```
ruleSet
```
RuleSet | null
```

seo

{ description?: string; title?: string; }

sortOrder
```
CollectionSortOrder
```
storefrontId
```
string
```
templateSuffix
```
string | null
```
title
```
string
```
updatedAt
```
string
```

Image

Configure the following properties on the image component.

src
The image source (either a remote URL or a local file resource). When the image is loading or no `src` is provided, a placeholder is rendered.
```
string
```
srcSet
A set of image sources and their width or pixel density descriptors. This overrides the `src` property. Learn more about the [srcset attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset).
```
string
```
sizes
A set of media conditions and their corresponding sizes. Learn more about the [sizes attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes).
```
string
```
alt
Alternative text that describes the image for accessibility. Provides a text description of the image for users with assistive technology and serves as a fallback when the image fails to load. A well-written description enables people with visual impairments to understand non-text content. When a screen reader encounters an image, it reads this description aloud. When an image fails to load, this text displays on screen, helping all users understand what content was intended. Learn more about [writing effective alt text](https://www.shopify.com/ca/blog/image-alt-text#4) and the [alt attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#alt).
```
string
```
aspectRatio
The aspect ratio of the image. The rendering of the image will depend on the `inlineSize` value: - `inlineSize="fill"`: the aspect ratio will be respected and the image will take the necessary space. - `inlineSize="auto"`: the image will not render until it has loaded and the aspect ratio will be ignored. For example, if the value is set as `50 / 100`, the getter returns `50 / 100`. If the value is set as `0.5`, the getter returns `0.5 / 1`. Learn more about the [aspect-ratio property](https://developer.mozilla.org/en-US/docs/Web/CSS/aspect-ratio).
```
`${number}` | `${number}/${number}` | `${number}/ ${number}` | `${number} /${number}` | `${number} / ${number}`
```
objectFit
The image resizing behavior to fit within its container. - `contain`: Scales the image to fit within the container while maintaining its aspect ratio. The entire image is visible, but might leave empty space. - `cover`: Scales the image to fill the entire container while maintaining its aspect ratio. The image might be cropped to fit. The image is always positioned in the center of the container. Learn more about the [object-fit property](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit).
```
"contain" | "cover"
```
loading
The loading strategy for the image. - `eager`: Immediately loads the image, irrespective of its position within the visible viewport. - `lazy`: Delays loading the image until it approaches a specified distance from the viewport. Learn more about the [loading attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading).
```
"eager" | "lazy"
```
accessibilityRole
The semantic meaning of the component’s content. When set, the role will be used by assistive technologies to help users navigate the page. - `none`: Completely hides the element and its content from assistive technologies - `presentation`: Removes semantic meaning, making the image purely decorative and ignored by screen readers. - `img`: Identifies the element as an image that conveys meaningful information to users.
```
"none" | "presentation" | "img"
```
inlineSize
The displayed inline width of the image. - `fill`: the image will takes up 100% of the available inline size. - `auto`: the image will be displayed at its natural size. Learn more about the [width attribute](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#width).
```
"auto" | "fill"
```
border
A border applied around the image using shorthand syntax to specify width, color, and style in a single property.
```
BorderShorthand
```
borderWidth
The thickness of the border around the image. When set, this overrides the width value specified in the `border` property.
```
"" | MaybeAllValuesShorthandProperty<"small" | "small-100" | "base" | "large" | "large-100" | "none">
```
borderStyle
The visual style of the border around the image, such as solid, dashed, or dotted. When set, this overrides the style value specified in the `border` property.
```
"" | MaybeAllValuesShorthandProperty<BoxBorderStyles>
```
borderColor
The color of the border around the image using the design system's color scale. When set, this overrides the color value specified in the `border` property.
```
"" | ColorKeyword
```
borderRadius
The roundedness of the image's corners using the design system's radius scale.
```
MaybeAllValuesShorthandProperty<BoxBorderRadii>
```
setAttribute
```
(name: string, value: string) => void
```
attributeChangedCallback
```
(name: string) => void
```
connectedCallback
```
() => void
```
disconnectedCallback
```
() => void
```
adoptedCallback
```
() => void
```
queueRender
A method that queues a run of the render function. You shouldn't need to call this manually - it should be handled by changes to
```
() => void
```
click
A method like the standard `element.click()`, but you can influence the behavior with a `sourceEvent`. For example, if the `sourceEvent` was a middle click, or has particular keys held down, components will attempt to produce the desired behavior on links, such as opening the page in the background tab.
```
({ sourceEvent }?: ClickOptions) => void
```

BorderShorthand

Represents a shorthand for defining a border. It can be a combination of size, optionally followed by color, optionally followed by style.

BorderSizeKeyword | `${BorderSizeKeyword} ${ColorKeyword}` | `${BorderSizeKeyword} ${ColorKeyword} ${BorderStyleKeyword}`

BorderSizeKeyword

Defines the width of borders, using the standard size scale or `none` for no border. - `SizeKeyword`: Standard border widths from the size scale for consistent thickness. - `none`: No border width (removes the border).

SizeKeyword | 'none'

SizeKeyword

Defines component sizes using a consistent scale from extra small to extra large. - `small-500` through `small-100`: Extra small to small sizes, progressively increasing. - `small`: Standard small size. - `base`: Default medium size that works well in most contexts. - `large`: Standard large size. - `large-100` through `large-500`: Large to extra large sizes, progressively increasing.

'small-500' | 'small-400' | 'small-300' | 'small-200' | 'small-100' | 'small' | 'base' | 'large' | 'large-100' | 'large-200' | 'large-300' | 'large-400' | 'large-500'

ColorKeyword

Defines the color intensity or emphasis level for text and UI elements. - `subdued`: Deemphasized color for secondary text, supporting labels, and less critical interface elements. - `base`: Primary color for body text, standard UI elements, and general content with good readability. - `strong`: Emphasized color for headings, key labels, and interactive elements that need prominence.

'subdued' | 'base' | 'strong'

BorderStyleKeyword

Defines the visual style of borders. - `none`: No border is displayed. - `solid`: A single solid line. - `dashed`: A series of short dashes. - `dotted`: A series of dots. - `auto`: Automatically determined based on context.

'none' | 'solid' | 'dashed' | 'dotted' | 'auto'

MaybeAllValuesShorthandProperty

Represents CSS shorthand properties that accept one to four values. Supports specifying values for all four sides: top, right, bottom, and left. - `T`: Single value that applies to all four sides. - `${T} ${T}`: Two values for block axis (top/bottom) and inline axis (left/right). - `${T} ${T} ${T}`: Three values for block-start (top), inline axis (left/right), and block-end (bottom). - `${T} ${T} ${T} ${T}`: Four values for block-start (top), inline-end (right), block-end (bottom), and inline-start (left).

T | `${T} ${T}` | `${T} ${T} ${T}` | `${T} ${T} ${T} ${T}`

BoxBorderStyles

Represents the subset of border style values supported by the box component. - `auto`: Default border style determined by the system. - `none`: No border style (removes the border). - `solid`: Continuous line border. - `dashed`: Border made up of dashes.

'auto' | 'none' | 'solid' | 'dashed'

BoxBorderRadii

Represents the subset of border radius values supported by the component. - `small-200`: Extra small radius for subtle rounding. - `small-100`: Small radius for minimal corner rounding. - `small`: Standard small radius. - `base`: Medium radius for moderate corner rounding. - `large`: Standard large radius for pronounced rounding. - `large-100`: Large radius for more prominent corner rounding. - `large-200`: Extra large radius for maximum rounding. - `none`: No border radius (sharp corners).

'small' | 'small-200' | 'small-100' | 'base' | 'large' | 'large-100' | 'large-200' | 'none'

RuleSet

appliedDisjunctively
```
boolean
```
rules
```
CollectionRule[]
```

CollectionRule

column
```
string
```
condition
```
string
```
relation
```
string
```

CollectionSortOrder

Manual
```
MANUAL
```
BestSelling
```
BEST_SELLING
```
AlphaAsc
```
ALPHA_ASC
```
AlphaDesc
```
ALPHA_DESC
```
PriceDesc
```
PRICE_DESC
```
PriceAsc
```
PRICE_ASC
```
CreatedDesc
```
CREATED_DESC
```
Created
```
CREATED
```
MostRelevant
```
MOST_RELEVANT
```

Product

availablePublicationCount
```
number
```
createdAt
```
string
```
descriptionHtml
```
string
```
handle
```
string
```
hasOnlyDefaultVariant
```
boolean
```
id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
images
```
Image[]
```

options

{ id: string; name: string; position: number; values: string[]; }[]

productType
```
string
```
publishedAt
```
string | null
```
status
```
ProductStatus
```
tags
```
string[]
```
templateSuffix
```
string | null
```
title
```
string
```
totalInventory
```
number
```
totalVariants
```
number
```
tracksInventory
```
boolean
```
updatedAt
```
string
```
variants
```
Partial<ProductVariant>[]
```
vendor
```
string
```

ProductStatus

Active
```
ACTIVE
```
Archived
```
ARCHIVED
```
Draft
```
DRAFT
```

ProductVariant

availableForSale
```
boolean
```
barcode
```
string | null
```
compareAtPrice
```
Money | null
```
createdAt
```
string
```
displayName
```
string
```

fulfillmentService

{ id: string; inventoryManagement: boolean; productBased: boolean; serviceName: string; type: FulfillmentServiceType; }

id
in GraphQL id format, ie 'gid://shopify/Product/1'
```
string
```
image
```
Image | null
```
inventoryItem
```
{ id: string; }
```
inventoryManagement
```
ProductVariantInventoryManagement
```
inventoryPolicy
```
ProductVariantInventoryPolicy
```
inventoryQuantity
```
number | null
```
position
```
number
```
price
```
Money
```
product
```
Partial<Product>
```
requiresShipping
```
boolean
```
selectedOptions
```
{ value?: string; }[]
```
sku
```
string | null
```
taxable
```
boolean
```
title
```
string
```
updatedAt
```
string
```
weight
```
number | null
```
weightUnit
```
WeightUnit
```

Money

string

FulfillmentServiceType

GiftCard
```
GIFT_CARD
```
Manual
```
MANUAL
```
ThirdParty
```
THIRD_PARTY
```

ProductVariantInventoryManagement

Shopify
```
SHOPIFY
```
NotManaged
```
NOT_MANAGED
```
FulfillmentService
```
FULFILLMENT_SERVICE
```

ProductVariantInventoryPolicy

Deny
```
DENY
```
Continue
```
CONTINUE
```

WeightUnit

Kilograms
```
KILOGRAMS
```
Grams
```
GRAMS
```
Pounds
```
POUNDS
```
Ounces
```
OUNCES
```

Examples

js

const selected = await shopify.resourcePicker({type: 'product'});

Preview

Examples

Description
Select products from the store catalog. This example opens a product resource picker and handles the selection response. The resource picker returns an array of product objects with GIDs, titles, and handles.
js
```
const selected = await shopify.resourcePicker({type: 'product'});
```
Description
Select collections or variants. This example selects collections instead of individual products by setting `type: "collection"`, or selects specific product variants by setting `type: "variant"`. Use collection mode for choosing product groupings, such as homepage featured collection carousels, navigation menu builders, or promotional campaigns. Use variant mode for choosing individual SKUs, useful for inventory tools, variant-specific promotions, or shipment builders.
Collections
```
const selected = await shopify.resourcePicker({type: 'collection'});
```
Product variants
```
const selected = await shopify.resourcePicker({type: 'variant'});
```
Description
Preselect products. This example opens the resource picker with products already selected by passing GIDs to the `selectionIds` option. Use this to pre-populate the picker with current selections for edit workflows, showing what products are already in a bundle, collection, or promotional set. Merchants can see current selections and modify them before confirming.
js
```
const selected = await shopify.resourcePicker({
  type: 'product',
  selectionIds: [
    {
      id: 'gid://shopify/Product/12345',
      variants: [
        {
          id: 'gid://shopify/ProductVariant/1',
        },
      ],
    },
    {
      id: 'gid://shopify/Product/67890',
    },
  ],
});
```
Description
Set action verb. This example customizes the resource picker button text by setting the `action` option to "add" or "select". "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.
js
```
const selected = await shopify.resourcePicker({
  type: 'product',
  action: 'select',
});
```
Description
Limit selection count. This example controls how many products merchants can select. Set `multiple: true` for unlimited selection useful for mass product taggers, bulk inventory tools, or export utilities. Set `multiple` to a number like `5` to limit selection count for bundle builders with item limits, featured product sections, or promotional campaigns with maximum product counts.
Unlimited selectable items
```
const selected = await shopify.resourcePicker({
  type: 'product',
  multiple: true,
});
```
Maximum selectable items
```
const selected = await shopify.resourcePicker({
  type: 'product',
  multiple: 5,
});
```
Description
Filter resources. This example filters the resource picker to show only specific products using the `filter` option. Use `variants: false` to hide variant information, `hidden: false` to exclude hidden products, `draft: false` to exclude draft products, or `archived: false` to exclude archived products. Combine filters to restrict the picker to live, customer-visible products.
js
```
const selected = await shopify.resourcePicker({
  type: 'product',
  filter: {
    hidden: true,
    variants: false,
    draft: false,
    archived: false,
  },
});
```
Description
Apply a filter query. This example applies a custom GraphQL search query using the `query` property in filters. The query runs server-side and is not visible to merchants. Use it to programmatically restrict results (for example, `vendor:Acme` or `tag:sale`) without exposing the filter logic.
js
```
const selected = await shopify.resourcePicker({
  type: 'product',
  filter: {
    query: 'Sweater',
  },
});
```
Description
Handle selection payload. This example handles the selection payload returned by the resource picker. When merchants confirm their selection, the picker returns an array of resource objects. When merchants cancel, it returns `undefined` rather than an empty array. Check for `undefined` explicitly to distinguish between cancellation and an empty selection.
js
```
const selected = await shopify.resourcePicker({type: 'product'});

if (selected) {
  console.log(selected);
} else {
  console.log('Picker was cancelled by the user');
}
```
Description
Start with search query. This example starts the resource picker with a pre-filled search query by passing the `query` option. This initializes the picker with a search term already entered, helpful when you know what merchants are likely looking for. Merchants can modify the query, but starting with relevant results saves time in large catalogs.
js
```
const selected = await shopify.resourcePicker({
  type: 'product',
  query: 'Sweater',
});
```

Was this page helpful?