--- 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 app needs merchants to choose Shopify resources to work with. api_name: app-home source_url: html: >- https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/resource-picker-api md: >- https://shopify.dev/docs/api/app-home/apis/user-interface-and-interactions/resource-picker-api.md --- # 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](https://shopify.dev/docs/api/app-bridge-library/apis/picker) API instead. ### Use 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. ### Inputs The `ResourcePickerOptions` object defines how the resource picker behaves, including which resource type to display, selection limits, filters, and preselected items. * **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. * **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. * **filter** **Filters** 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. * **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`. * **query** **string** **Default: ''** Initial GraphQL search query for filtering resources available in the resource picker. See [search syntax](https://shopify.dev/docs/api/usage/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. * **selectionIds** **BaseResource\[]** **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. ```ts 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. ```ts boolean | undefined ``` * hidden Whether to show hidden resources, referring to products that are not published on any sales channels. ```ts 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. ```ts string ``` * variants Whether to show product variants. Only applies to the Product resource type picker. ```ts boolean ``` ### BaseResource * id in GraphQL id format, ie 'gid://shopify/Product/1' ```ts string ``` * variants ```ts Resource[] ``` ### Resource * id in GraphQL id format, ie 'gid://shopify/Product/1' ```ts string ``` ### 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. * **when type is "collection":** **Collection\[]** * **when type is "product":** **Product\[]** * **when type is "variant":** **ProductVariant\[]** ### Collection * availablePublicationCount ```ts number ``` * description ```ts string ``` * descriptionHtml ```ts string ``` * handle ```ts string ``` * id in GraphQL id format, ie 'gid://shopify/Product/1' ```ts string ``` * image ```ts Image | null ``` * productsAutomaticallySortedCount ```ts number ``` * productsCount ```ts number ``` * productsManuallySortedCount ```ts number ``` * publicationCount ```ts number ``` * ruleSet ```ts RuleSet | null ``` * seo ```ts { description?: string; title?: string; } ``` * sortOrder ```ts CollectionSortOrder ``` * storefrontId ```ts string ``` * templateSuffix ```ts string | null ``` * title ```ts string ``` * updatedAt ```ts 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. ```ts 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). ```ts 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). ```ts 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). ```ts 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). ```ts `${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). ```ts "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). ```ts "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. ```ts "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). ```ts "auto" | "fill" ``` * border A border applied around the image using shorthand syntax to specify width, color, and style in a single property. ```ts BorderShorthand ``` * borderWidth The thickness of the border around the image. When set, this overrides the width value specified in the \`border\` property. ```ts "" | 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. ```ts "" | MaybeAllValuesShorthandProperty ``` * 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. ```ts "" | ColorKeyword ``` * borderRadius The roundedness of the image's corners using the design system's radius scale. ```ts MaybeAllValuesShorthandProperty ``` * setAttribute ```ts (name: string, value: string) => void ``` * attributeChangedCallback ```ts (name: string) => void ``` * connectedCallback ```ts () => void ``` * disconnectedCallback ```ts () => void ``` * adoptedCallback ```ts () => 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 ```ts () => 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. ```ts ({ 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. ```ts 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). ```ts 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. ```ts '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. ```ts '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. ```ts '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). ```ts 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. ```ts '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). ```ts 'small' | 'small-200' | 'small-100' | 'base' | 'large' | 'large-100' | 'large-200' | 'none' ``` ### RuleSet * appliedDisjunctively ```ts boolean ``` * rules ```ts CollectionRule[] ``` ### CollectionRule * column ```ts string ``` * condition ```ts string ``` * relation ```ts string ``` ### CollectionSortOrder * Manual ```ts MANUAL ``` * BestSelling ```ts BEST_SELLING ``` * AlphaAsc ```ts ALPHA_ASC ``` * AlphaDesc ```ts ALPHA_DESC ``` * PriceDesc ```ts PRICE_DESC ``` * PriceAsc ```ts PRICE_ASC ``` * CreatedDesc ```ts CREATED_DESC ``` * Created ```ts CREATED ``` * MostRelevant ```ts MOST_RELEVANT ``` ### Product * availablePublicationCount ```ts number ``` * createdAt ```ts string ``` * descriptionHtml ```ts string ``` * handle ```ts string ``` * hasOnlyDefaultVariant ```ts boolean ``` * id in GraphQL id format, ie 'gid://shopify/Product/1' ```ts string ``` * images ```ts Image[] ``` * options ```ts { id: string; name: string; position: number; values: string[]; }[] ``` * productType ```ts string ``` * publishedAt ```ts string | null ``` * status ```ts ProductStatus ``` * tags ```ts string[] ``` * templateSuffix ```ts string | null ``` * title ```ts string ``` * totalInventory ```ts number ``` * totalVariants ```ts number ``` * tracksInventory ```ts boolean ``` * updatedAt ```ts string ``` * variants ```ts Partial[] ``` * vendor ```ts string ``` ### ProductStatus * Active ```ts ACTIVE ``` * Archived ```ts ARCHIVED ``` * Draft ```ts DRAFT ``` ### ProductVariant * availableForSale ```ts boolean ``` * barcode ```ts string | null ``` * compareAtPrice ```ts Money | null ``` * createdAt ```ts string ``` * displayName ```ts string ``` * fulfillmentService ```ts { id: string; inventoryManagement: boolean; productBased: boolean; serviceName: string; type: FulfillmentServiceType; } ``` * id in GraphQL id format, ie 'gid://shopify/Product/1' ```ts string ``` * image ```ts Image | null ``` * inventoryItem ```ts { id: string; } ``` * inventoryManagement ```ts ProductVariantInventoryManagement ``` * inventoryPolicy ```ts ProductVariantInventoryPolicy ``` * inventoryQuantity ```ts number | null ``` * position ```ts number ``` * price ```ts Money ``` * product ```ts Partial ``` * requiresShipping ```ts boolean ``` * selectedOptions ```ts { value?: string; }[] ``` * sku ```ts string | null ``` * taxable ```ts boolean ``` * title ```ts string ``` * updatedAt ```ts string ``` * weight ```ts number | null ``` * weightUnit ```ts WeightUnit ``` ### Money ```ts string ``` ### FulfillmentServiceType * GiftCard ```ts GIFT_CARD ``` * Manual ```ts MANUAL ``` * ThirdParty ```ts THIRD_PARTY ``` ### ProductVariantInventoryManagement * Shopify ```ts SHOPIFY ``` * NotManaged ```ts NOT_MANAGED ``` * FulfillmentService ```ts FULFILLMENT_SERVICE ``` ### ProductVariantInventoryPolicy * Deny ```ts DENY ``` * Continue ```ts CONTINUE ``` ### WeightUnit * Kilograms ```ts KILOGRAMS ``` * Grams ```ts GRAMS ``` * Pounds ```ts POUNDS ``` * Ounces ```ts OUNCES ``` Examples ## Preview ![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.](https://shopify.dev/assets/assets/images/templated-apis-screenshots/admin/apis/resource-picker-DeAqlQby.png) ### 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 ```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 ```js const selected = await shopify.resourcePicker({type: 'collection'}); ``` ##### Product variants ```js 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 ```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 ```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 ```js const selected = await shopify.resourcePicker({ type: 'product', multiple: true, }); ``` ##### Maximum selectable items ```js 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 ```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 ```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 ```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 ```js const selected = await shopify.resourcePicker({ type: 'product', query: 'Sweater', }); ``` ***