> Note: > This is a legacy API. Use the latest version of [`Resource Picker`](/docs/api/app-bridge-library/apis/resource-picker) instead. The `ResourcePicker` action set provides a search-based interface to help users find and select one or more products, collections, or product variants, and then returns the selected resources to your app. A close-up image of a resource picker. The resource picker displays the title: Add products and a search input field with the label: Search products. Below the search interface are rows of placeholder resources. Product 1 and variant 1 are both selected. The picker features two buttons: a white button with the label Cancel, and a green button with the label Add. You can use the resoure picker action set in the following ways: 1. [Plain JavaScript](#plain-javascript) 2. [React component](#react) ## Plain JavaScript ### Example code Create an app and import the `ResourcePicker` module from `@shopify/app-bridge/actions`. Note that we'll be referring to this sample application throughout the examples below. > Note > In the following example, `config` is a valid App Bridge configuration object. Learn more about [configuring App Bridge](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app). ```js import createApp from '@shopify/app-bridge'; import {ResourcePicker} from '@shopify/app-bridge/actions'; const app = createApp(config); ``` ### Create a product picker ```js const productPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Product, }); ``` ### Create a product variant picker ```js const variantPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.ProductVariant, }); ``` ### Create a collection picker ```js const collectionPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Collection, }); ``` ### Picker selection and cancellation Resource pickers have two main actions that you can subscribe to: * `ResourcePicker.Action.CANCEL` - App Bridge dispatches this action when the user cancels the resource picker, without making a selection. * `ResourcePicker.Action.SELECT` - App Bridge dispatches this action after the user confirms a selection. This action provides a `SelectPayload`: an `Object` with `id` and `selection` keys. The `selection` key is an array of all the selected resources. ```js const picker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Product, }); picker.subscribe(ResourcePicker.Action.CANCEL, () => { // Picker was cancelled }); picker.subscribe(ResourcePicker.Action.SELECT, (selectPayload) => { const selection = selectPayload.selection; // Do something with `selection` }); ``` > Note > If you require additional information about the selected resources, then query the [GraphQL Admin API](/docs/api/admin-graphql). ### Options #### initialQuery * default value: `undefined` * optional * type: `string` * note: Prepopulates the search bar of the resource picker. #### initialSelectionIds * default value: `[]` * optional * type: `Resource[]` * note: `initialSelectionIds` takes an array of minimal resource objects, which only need to contain a resource ID (in GraphQL ID format, ie `'gid://shopify/Product/1'`). Product resources may also contain selected variants. If no variants are specified, all variants will be selected. ```js const productWithSpecificVariantsSelected = { id: 'gid://shopify/Product/12345', variants: [{ id: 'gid://shopify/ProductVariant/1', }], }; const productWithAllVariantsSelected = { id: 'gid://shopify/Product/67890', }; const productPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Product, options: { initialSelectionIds: [productWithVariantsSelected, productWithAllVariantsSelected], }, }); ``` #### actionVerb * default value: `ResourcePicker.ActionVerb.Add` * optional * type: `ResourcePicker.ActionVerb` (values: `Add`, `Select`) * note: The actionVerb appears in the title ` ` and as the primary action of the resource picker. #### selectMultiple * default value: `true` * optional * type: `boolean` or `number` * note: Whether to allow selecting multiple items of a specific `resourceType` or not. If a number is provided, then limit the selections to a maximum of that number of items. Providing a number requires version 1.28.0. When `resourceType` is `Product`, the user may still select multiple variants of a single product, even if `selectMultiple` is `false`. ### Boolean options **Option**|**Default**|**Optional**|**Version**|**Note** :-----|:-----|:-----:|:-----|:----- `showHidden`|`true`|✔️||`hidden` refers to products that are not published on any sales channels.| `showVariants`|`true`|✔️||Only applies to the `Product` resource type picker.| `showDraft`|`true`|✔️|1.28.0|Whether to show [draft products](https://help.shopify.com/manual/products/details#product-availability) or not. Only applies to the `Product` resource type picker.| `showArchived`|`true`|✔️|1.28.0| Whether to show [archived products](https://help.shopify.com/manual/products/details#product-availability) or not. Only applies to the `Product` resource type picker.| `showDraftBadge`|`false`|✔️|1.28.0|Whether to show draft badge for [draft products](https://help.shopify.com/manual/products/details#product-availability) or not. Only works when `showDraft` prop is set, and only applies to the `Product` resource type picker.| `showArchivedBadge`|`false`|✔️|1.28.0|Whether to show archived badge for [archived products](https://help.shopify.com/manual/products/details#product-availability) or not. Only works when `showArchived` prop is set, and only applies to the `Product` resource type picker.| ### Subscribe You can subscribe to modal actions by calling `subscribe`. This returns a function that you can call to unsubscribe from the action: ```js const productPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Product, options: { selectMultiple: true, showHidden: false, }, }); const selectUnsubscribe = productPicker.subscribe(ResourcePicker.Action.SELECT, ({selection}) => { // Do something with `selection` }); const cancelUnsubscribe = productPicker.subscribe(ResourcePicker.Action.CANCEL, () => { // Picker was cancelled }); // Unsubscribe to actions selectUnsubscribe(); cancelUnsubscribe(); ``` ### Unsubscribe You can call `unsubscribe` to remove all subscriptions on the resource picker: ```js const productPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Product, options: { selectMultiple: true, showHidden: false, }, }); productPicker.subscribe(ResourcePicker.Action.SELECT, () => { // Do something with `selection` }); productPicker.subscribe(ResourcePicker.Action.CANCEL, () => { // Do something when the ResourcePicker is cancelled }); // Unsubscribe from all actions productPicker.unsubscribe(); ``` ### Dispatch actions ```js const collectionPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Collection, options: { selectMultiple: true, showHidden: false, } }); // Open the collection picker collectionPicker.dispatch(ResourcePicker.Action.OPEN); ``` ### Update options You can call the `set` method with partial picker options. This automatically triggers the `update` action on the modal and merges the given options with the existing options: ```js const collectionPicker = ResourcePicker.create(app, { resourceType: ResourcePicker.ResourceType.Collection, options: { selectMultiple: true, showHidden: false, }, }); collectionPicker.set({showHidden: true}); ``` ## React ### Example code Import the `ResourcePicker` component from `@shopify/app-bridge-react`. > Note > In the following example, `config` is a valid App Bridge configuration object. Learn more about [configuring App Bridge](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/app-setup#initialize-shopify-app-bridge-in-your-app). > Note > When using the App Bridge React library, you need to wrap all of your App Bridge React code inside of a single App Bridge [`Provider`](/docs/api/app-bridge/previous-versions/app-bridge-from-npm/using-react#provider). ```jsx import React from 'react'; import ReactDOM from 'react-dom'; import {Provider, ResourcePicker} from '@shopify/app-bridge-react'; function MyApp() { return ( ); } const root = document.createElement('div'); document.body.appendChild(root); ReactDOM.createRoot(root).render(); ``` ### Props |Name|Type|Description|Required| |---|---|---|---| |open|`boolean`|Whether the picker is open or not|Yes| |resourceType|`"Product"`, `"ProductVariant"`, `"Collection"`|The type of resource you want to pick|Yes| |initialQuery|`string`|GraphQL initial search query for filtering resources available in the picker. See [search syntax](/docs/api/usage/search-syntax) for more information|| |initialSelectionIds|`Resource[]`|Resources that should be preselected when the picker is opened. See [example below](#initialselectionids).|| |showHidden|`boolean`|Whether to show hidden products or not|| |selectMultiple|`boolean`|Whether to allow selecting multiple items of a specific `resourceType` or not. If a number is provided, then limit the selections to a maximum of that number of items. Providing a number requires version 1.28.0. When `resourceType` is `Product`, the user may still select multiple variants of a single product, even if `selectMultiple` is `false`. |showVariants|`boolean`|Whether to show product variants or not. Only applies to the product resource type picker. Requires version 1.28.0.|| |showDraft|`boolean`|Whether to show [draft products](https://help.shopify.com/manual/products/details#product-availability) or not. Only applies to the `Product` resource type picker. Requires version 1.28.0.|| |showArchived|`boolean`|Whether to show [archived products](https://help.shopify.com/manual/products/details#product-availability) or not. Only applies to the `Product` resource type picker. Requires version 1.28.0.|| |showDraftBadge|`boolean`|Whether to show draft badge for [draft products](https://help.shopify.com/manual/products/details#product-availability) or not. Only works when the `showDraft` prop is set, and only applies to the `Product` resource type picker. Requires version 1.28.0.|| |showArchivedBadge|`boolean`|Whether to show archived badge for [archived products](https://help.shopify.com/manual/products/details#product-availability) or not. Only works when the `showArchived` prop is set, and only applies to the `Product` resource type picker. Requires version 1.28.0.|| |onSelection|`(selectPayload: SelectPayload) => void`|Callback when a selection has been made. It receives a `SelectPayload` argument, which is an `Object` with `id` and `selection` keys. The `selection` key is an array of all the selected resources.|| |onCancel|`() => void`|Callback when the picker is closed without selection|| ### initialSelectionIds Use the `initialSelectionIds` prop to specify resources that should already be selected when the picker is opened: ```jsx const productWithSpecificVariantsSelected = { id: 'gid://shopify/Product/12345', variants: [{ id: 'gid://shopify/ProductVariant/1', }], }; const productWithAllVariantsSelected = { id: 'gid://shopify/Product/67890', }; function myComponent() { return } ```