Skip to main content

ResourcePicker

Note

This is a legacy API. Use the latest version of 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
  2. React component

Anchor to Plain JavaScriptPlain JavaScript

Anchor to Example codeExample 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.

import createApp from '@shopify/app-bridge';
import {ResourcePicker} from '@shopify/app-bridge/actions';

const app = createApp(config);

Anchor to Create a product pickerCreate a product picker

const productPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Product,
});

Anchor to Create a product variant pickerCreate a product variant picker

const variantPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.ProductVariant,
});

Anchor to Create a collection pickerCreate a collection picker

const collectionPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Collection,
});

Anchor to Picker selection and cancellationPicker 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.
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.

Anchor to OptionsOptions

Anchor to initialQueryinitialQuery

  • default value: undefined
  • optional
  • type: string
  • note: Prepopulates the search bar of the resource picker.

Anchor to initialSelectionIdsinitialSelectionIds

  • 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.
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],
},
});

Anchor to actionVerbactionVerb

  • default value: ResourcePicker.ActionVerb.Add
  • optional
  • type: ResourcePicker.ActionVerb (values: Add, Select)
  • note: The actionVerb appears in the title <actionVerb> <resourceType> and as the primary action of the resource picker.

Anchor to selectMultipleselectMultiple

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

Anchor to Boolean optionsBoolean options

OptionDefaultOptionalVersionNote
showHiddentrue✔️hidden refers to products that are not published on any sales channels.
showVariantstrue✔️Only applies to the Product resource type picker.
showDrafttrue✔️1.28.0Whether to show draft products or not. Only applies to the Product resource type picker.
showArchivedtrue✔️1.28.0Whether to show archived products or not. Only applies to the Product resource type picker.
showDraftBadgefalse✔️1.28.0Whether to show draft badge for draft products or not. Only works when showDraft prop is set, and only applies to the Product resource type picker.
showArchivedBadgefalse✔️1.28.0Whether to show archived badge for archived products or not. Only works when showArchived prop is set, and only applies to the Product resource type picker.

Anchor to SubscribeSubscribe

You can subscribe to modal actions by calling subscribe. This returns a function that you can call to unsubscribe from the action:

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

Anchor to UnsubscribeUnsubscribe

You can call unsubscribe to remove all subscriptions on the resource picker:

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

Anchor to Dispatch actionsDispatch actions

const collectionPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Collection,
options: {
selectMultiple: true,
showHidden: false,
}
});

// Open the collection picker
collectionPicker.dispatch(ResourcePicker.Action.OPEN);

Anchor to Update optionsUpdate 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:

const collectionPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Collection,
options: {
selectMultiple: true,
showHidden: false,
},
});

collectionPicker.set({showHidden: true});

Anchor to ReactReact

Anchor to Example codeExample 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.

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.

import React from 'react';
import ReactDOM from 'react-dom';
import {Provider, ResourcePicker} from '@shopify/app-bridge-react';

function MyApp() {
return (
<Provider config={config}>
<ResourcePicker resourceType="Product" open />
</Provider>
);
}

const root = document.createElement('div');
document.body.appendChild(root);
ReactDOM.createRoot(root).render(<MyApp />);

Anchor to PropsProps

NameTypeDescriptionRequired
openbooleanWhether the picker is open or notYes
resourceType"Product", "ProductVariant", "Collection"The type of resource you want to pickYes
initialQuerystringGraphQL initial search query for filtering resources available in the picker. See search syntax for more information
initialSelectionIdsResource[]Resources that should be preselected when the picker is opened. See example below.
showHiddenbooleanWhether to show hidden products or not
selectMultiplebooleanWhether 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.
showVariantsbooleanWhether to show product variants or not. Only applies to the product resource type picker. Requires version 1.28.0.
showDraftbooleanWhether to show draft products or not. Only applies to the Product resource type picker. Requires version 1.28.0.
showArchivedbooleanWhether to show archived products or not. Only applies to the Product resource type picker. Requires version 1.28.0.
showDraftBadgebooleanWhether to show draft badge for draft products or not. Only works when the showDraft prop is set, and only applies to the Product resource type picker. Requires version 1.28.0.
showArchivedBadgebooleanWhether to show archived badge for archived products 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) => voidCallback 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() => voidCallback when the picker is closed without selection

Anchor to initialSelectionIdsinitialSelectionIds

Use the initialSelectionIds prop to specify resources that should already be selected when the picker is opened:

const productWithSpecificVariantsSelected = {
id: 'gid://shopify/Product/12345',
variants: [{
id: 'gid://shopify/ProductVariant/1',
}],
};

const productWithAllVariantsSelected = {
id: 'gid://shopify/Product/67890',
};

function myComponent() {
return <ResourcePicker
initialSelectionIds={[
productWithVariantsSelected,
productWithAllVariantsSelected
]}
/>
}
Was this page helpful?