ResourcePicker
The ResourcePicker
action set provides a search-based interface to help merchants find and select one or more products, collections, or product variants, and then returns the selected resources to your app.
Setup
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.
import createApp from '@shopify/app-bridge';
import {ResourcePicker} from '@shopify/app-bridge/actions';
const app = createApp({
apiKey: '12345',
shopOrigin: shopOrigin,
});
Create a product picker
const productPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Product,
});
Create a product variant picker
const variantPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.ProductVariant,
});
Create a collection picker
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 aSelectPayload
: anObject
withid
andselection
keys. Theselection
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`
});
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.
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
<actionVerb> <resourceType>
and as the primary action of the resource picker.
selectMultiple
- default value:
true
- optional
- type:
boolean
ornumber
- note: Whether to allow selecting multiple items 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.
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 or not. Only applies to the Product resource type picker. |
showArchived |
true |
✔️ | 1.28.0 | Whether to show archived products or not. Only applies to the Product resource type picker. |
showDraftBadge |
false |
✔️ | 1.28.0 | Whether 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. |
showArchivedBadge |
false |
✔️ | 1.28.0 | Whether 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. |
Subscribe to actions
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();
Unsubscribe
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, () => {
// Picker was cancelled
});
// Unsubscribe from all actions
productPicker.unsubscribe();
Dispatch actions
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:
const collectionPicker = ResourcePicker.create(app, {
resourceType: ResourcePicker.ResourceType.Collection,
options: {
selectMultiple: true,
showHidden: false,
},
});
collectionPicker.set({showHidden: true});