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

<img alt="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." src="/assets/apps/tools/app-bridge-resource-picker.png" style="display: block; width: 100%; max-width: 524px">

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 `<actionVerb> <resourceType>` 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 (
    <Provider config={config}>
      <ResourcePicker resourceType="Product" open />
    </Provider>
  );
}

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

### 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 <ResourcePicker
    initialSelectionIds={[
      productWithVariantsSelected,
      productWithAllVariantsSelected
    ]}
  />
}
```