• Plain JavaScript
  • React

unstable_Picker

The Picker action set provides a search-based interface to help users find and select one or more resources. Unlike the ResourcePicker, it provides a lower-level API where you are in charge of providing the data as well as implementing search or pagination features.

A close-up image of a picker. The picker displays the title: Picker and a search input field with the label: Search resources. Below the search interface are rows of placeholder resources. Resource 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 Select.

You can use the contextual save bar in the following ways:

  1. Plain JavaScript
  2. React component

Caution

This feature is still under development. As such, the API might be updated without warning.

Plain JavaScript

Anchor link to section titled "Plain JavaScript"

Create an app and import the unstable_Picker module from @shopify/app-bridge/actions. This sample app is used throughout the examples below.

Note

In the following example, config is a valid App Bridge configuration object. Learn more about configuring App Bridge.

Create a picker to display a list of resources

Anchor link to section titled "Create a picker to display a list of resources"

The following snippet creates a Picker with 2 resources. The first resource has 2 options. We're also specifying the title, search placeholder, and action labels.

Common Picker actions

Anchor link to section titled "Common Picker actions"

Selection and Cancellation

Anchor link to section titled "Selection and Cancellation"

The Picker has two main actions that you can subscribe to:

unstable_Picker.Action.SELECT - This action is dispatched when the user triggers the primary action. This action generally corresponds to a selection event. It receives a SelectPayload argument, which is an Object with id and selection keys. The selection key is an array of all the selected items.

unstable_Picker.Action.CANCEL - This action is dispatched when the user triggers the secondary action. This action generally corresponds to a cancelled event.

Search

Anchor link to section titled "Search"

The Picker has the unstable_Picker.Action.SEARCH search action that you can subscribe to.

This action is dispatched when the user enters a search query string. It receives a SearchPayload argument, which is an Object with id and searchQuery. The searchQuery is a string.

Pagination

Anchor link to section titled "Pagination"

The Picker has the unstable_Picker.Action.LOAD_MORE pagination action that you can subscribe to. To enable this option make sure to set canLoadMore to true when creating your picker instance.

This action is dispatched when the user reaches the bottom of the list of items. It does not have any arguments.

Options

Anchor link to section titled "Options"

items

Anchor link to section titled "items"
  • default value: []
  • optional
  • type: BaseResource[]
  • note: items takes an array of minimal resource objects, which only need to contain a resource id and a name value. A resource may also contain child options. For example:

selectedItems

Anchor link to section titled "selectedItems"
  • default value: []
  • optional
  • type: BaseResource[]
  • note: selectedItems takes an array of minimal resource objects, which only need to contain a resource id (in GraphQL ID format, ie 'gid://shopify/Product/1'). Resources may also contain selected options. If no option is specified, all options are selected.

maxSelectable

Anchor link to section titled "maxSelectable"
  • default value: 0
  • optional
  • type: number
  • note: Limits the total number of selections to a maximum of the passed value, or 0 for no limit.

title

Anchor link to section titled "title"
  • default value: undefined
  • optional
  • type: string
  • note: Used as the title of the modal.

loading

Anchor link to section titled "loading"
  • default value: false
  • optional
  • type: boolean
  • note: Indicates if the picker should be in a loading state.

searchQueryPlaceholder

Anchor link to section titled "searchQueryPlaceholder"
  • default value: undefined
  • optional
  • type: string
  • note: Used as the placeholder in the search input.

searchQuery

Anchor link to section titled "searchQuery"
  • default value: undefined
  • optional
  • type: string
  • note: The search query to be displayed in the search input field.

primaryActionLabel

Anchor link to section titled "primaryActionLabel"
  • default value: undefined
  • optional
  • type: string
  • note: Label to be used on the primary action button.

secondaryActionLabel

Anchor link to section titled "secondaryActionLabel"
  • default value: undefined
  • optional
  • type: string
  • note: Label to be used on the secondary action button.

canLoadMore

Anchor link to section titled "canLoadMore"
  • default value: false
  • optional
  • type: boolean
  • note: Whether the Picker can load more items on the list.

loadingMore

Anchor link to section titled "loadingMore"
  • default value: false
  • optional
  • type: boolean
  • note: Indicates if the Picker is currently loading more items.

emptySearchLabel

Anchor link to section titled "emptySearchLabel"
  • default value: undefined
  • optional
  • type: EmptySearchLabel
  • note: emptySearchLabel takes an object that describes the interface of the picker when there is no item to display. For example:

Subscribe to actions

Anchor link to section titled "Subscribe to actions"

You can subscribe to Picker actions by calling subscribe. This returns a method that you can call to unsubscribe from the action. For example:

Unsubscribe

Anchor link to section titled "Unsubscribe"

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

Dispatch actions

Anchor link to section titled "Dispatch actions"

Update options

Anchor link to section titled "Update options"

You can call the set method with partial picker options. This automatically triggers the update action on the picker and merges the given options with the existing options:

React

Anchor link to section titled "React"

Example code

Anchor link to section titled "Example code"

Import the Provider and unstable_Picker 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.

Props

Anchor link to section titled "Props"
Name Type Description Required
open boolean Whether the picker is open or not. Yes
items BaseResource[] The list of items to display. Yes
canLoadMore boolean Whether the Picker can load more items on the list. No
selectedItems BaseResource[] The items which are selected. No
maxSelectable number Limits the total number of selections to a maximum of the passed value, or 0 for no limit. No
title string Used as the title of the modal. No
loading boolean Indicates if the Picker should be in a loading state. No
loadingMore boolean Indicates if the Picker is currently loading more items. No
searchQueryPlaceholder string Used as the placeholder in the search input. No
searchQuery string The search query to be displayed in the search input field. No
primaryActionLabel string Label to be used on the primary action button. No
secondaryActionLabel string Label to be used on the secondary action button. No
emptySearchLabel EmptySearchLabel An object that describes the interface of the picker when there is no item to display. No
onCancel () => void Callback when the user triggers the secondary action. No
onSelect (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. No
onSearch (searchPayload: SearchPayload) => void Callback when the user enters a search query string. It receives a SearchPayload argument, which is an Object with id and searchQuery. The searchQuery is a string. No
onLoadMore () => void Callback when the user reaches the bottom of the list of items. It does not have any argument. No

On this page

  • Plain JavaScript
  • React