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 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`
});

Options

initialQuery

  • default value: undefined
  • optional
  • type: string

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 productWithVariantsSelected = {
  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],
  },
});

selectMultiple

  • default value: true
  • optional
  • type: boolean

showHidden

  • default value: true
  • optional
  • type: boolean
  • note: showHidden refers to products that are not published on the Online Store

showVariants

  • default value: true
  • optional
  • type: string
  • note: Only applies to the Product resource type picker

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.

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

On this page