> Portal Navigation:
>
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt
## Resource: openItemSelector()
## Article: itemSelector
## Article Link: https://dev.wix.com/docs/sdk/host-modules/workspace/item-selector/open-item-selector.md
## Article Content:
# openItemSelector()
Opens an item selection modal that lets Wix users select items from a Wix service without leaving the dashboard. For example, Wix users can select products to feature in a store, pick blog posts for a custom layout, or choose contacts for a mailing list.
__Important:__
This method is only available in the dashboard. It requires the [workspace host to be initialized](https://dev.wix.com/docs/sdk/host-modules/workspace/introduction.md) and an updated version of the host initialization package to be installed.
## Import statement
```js
import { itemSelector } from "@wix/workspace";
```
## Method declaration
```js
function openItemSelector(
providerKey: string,
options?: Omit
): Promise;
```
## Parameters
| Name | Type | Description |
| ---- | ---- | ----------- |
| `providerKey` | string | Identifies the Wix service to load items from, determining what appears in the selector modal. For example, specifying the Products key loads items from the Wix Stores catalog. For supported values, see [Available providers](#available-providers). |
| `options` | [ItemSelectionOptions](#itemselectionoptions) (optional) | Configuration options for the item selection modal. |
## Returns
A promise that resolves to an [`ItemSelectionResult`](#itemselectionresult) containing the selected items.
## Available providers
The following table lists all available providers and the Wix business solutions that must be installed on a site for each provider to work.
| Provider | providerKey | Description | Site requirements |
| -------- | ------------- | ----------- | ----------------- |
| Products | `215238eb-22a5-4c36-9e7b-e7c08025e04e_products` | Products from the Wix Stores catalog. | [Wix Stores](https://www.wix.com/app-market/web-solution/wix-stores) installed. |
| Categories | `215238eb-22a5-4c36-9e7b-e7c08025e04e_categoriesCatalogV3` | Product categories defined in Wix Stores. | [Wix Stores](https://www.wix.com/app-market/web-solution/wix-stores) installed. |
| Coupons | `14d7032a-0a65-5270-cca7-30f599708fed_couponsPicker` | Discount coupons from Wix Stores. | [Wix Stores](https://www.wix.com/app-market/web-solution/wix-stores) installed. |
| Blog Posts | `14bcded7-0066-7c35-14d7-466cb3f09103_blogPostSelectionService` | Published blog posts from Wix Blog. | [Wix Blog](https://www.wix.com/app-market/web-solution/blog) installed. |
| Contacts | `74bff718-5977-47f2-9e5f-a9fd0047fd1f_ContactsItemsSelectionProvider` | Contacts from the CRM contact list. | Installed on all Wix sites by default. |
| Labels | `74bff718-5977-47f2-9e5f-a9fd0047fd1f_LabelsItemsSelection` | Contact labels used to organize CRM contacts. | Installed on all Wix sites by default. |
| Assignees | `f8859728-6fe9-49e6-8c63-8c7abf593087_AssigneesItemsSelectionProvider` | Team members to assign to a task or item. | Installed on all Wix sites by default. |
| Members | `14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9_members1` | Registered site members, searchable by login email. | [Wix Members Area](https://www.wix.com/app-market/web-solution/members-area) installed. |
| Badges | `14cc59bc-f0b7-15b8-e1c7-89ce41d0e0c9_BadgesSelectionProvider` | Badges available to assign to site members. | [Wix Members Area](https://www.wix.com/app-market/web-solution/members-area) installed. |
| Invoices | `13ee94c1-b635-8505-3391-97919052c16f_InvoiceSelectionProvider2` | Invoices from Wix Invoices. | Installed on all Wix sites by default. |
| Price Quotes | `55cd9036-36bb-480b-8ddc-afda3cb2eb8d_PriceQuoteSelectionProvider2` | Price quotes from Wix Price Quotes. | Installed on all Wix sites by default. |
| Email Campaigns | `135c3d92-0fea-1f9d-2ba5-2a1dfb04297e_campaignSelectionProvider` | Email marketing campaigns for the site. | Installed on all Wix sites by default. |
| Locations | `5b039bea-c008-4c3a-a717-24bc9388bf8c_LocationsProvider` | Business locations defined in Business Info. | Installed on all Wix sites by default. |
| Site Pages | `14517e1a-3ff0-af98-408e-2bd6953c36a2_SitePage` | Pages on a site. | Installed on all Wix sites by default. |
## Objects
### Item
Represents a selectable item in the item selector modal.
| Name | Type | Description |
| -------- | ---- | ----------- |
| `id` | string | Item ID. |
| `name` | string | **Optional.** Item name. |
| `description` | string | **Optional.** Item description. |
| `image` | object | **Optional.** Item image. Contains a `url` property with the image URL. |
| `note` | string | **Optional.** Additional information about the item, such as price. |
| `additionalFields` | object | **Optional.** Additional properties associated with the item. The available properties vary by provider. |
### ItemSelectionOptions
Configuration options for the item selection modal.
| Name | Type | Description |
| -------- | ---- | ----------- |
| `maxSelected` | number | **Optional.** The maximum number of items Wix users can select in the modal. Default: `1` |
| `primaryButtonText` | string | **Optional.** Custom text for the primary action button in the modal. |
| `title` | string | **Optional.** Custom title for the modal. |
| `initialSelect` | string[] | **Optional.** IDs of items that appear as selected when the modal opens. |
### ItemSelectionResult
Result returned from the item selection modal.
| Name | Type | Description |
| -------- | ---- | ----------- |
| `items` | Item[] | Array of selected items. |
## Examples
Open an item selector modal to select products:
```js
import { itemSelector } from "@wix/workspace";
try {
const result = await itemSelector.openItemSelector(
"215238eb-22a5-4c36-9e7b-e7c08025e04e_products",
{
maxSelected: 3,
title: "Select Products",
primaryButtonText: "Add Selected Products"
}
);
console.log("Selected items:", result.items);
result.items.forEach(item => {
console.log(`Item: ${item.name} (ID: ${item.id})`);
if (item.image?.url) {
console.log(`Image URL: ${item.image.url}`);
}
if (item.note) {
console.log(`Note: ${item.note}`);
}
});
} catch (error) {
console.error("Failed to open item selector:", error.message);
}
```
Open an item selector modal with pre-selected items:
```js
import { itemSelector } from "@wix/workspace";
try {
const result = await itemSelector.openItemSelector(
"215238eb-22a5-4c36-9e7b-e7c08025e04e_products",
{
maxSelected: 5,
title: "Update Product Selection",
initialSelect: ["product1", "product2"], // Pre-select these items
primaryButtonText: "Update Selection"
}
);
console.log(`Selected ${result.items.length} items:`, result.items);
} catch (error) {
console.error("Failed to open item selector:", error.message);
}
```
## Errors
The method may throw errors in the following cases:
- **The workspace host isn't available on the current host environment.**
This method only works inside the Wix dashboard. Make sure you're calling it from a dashboard extension, not from a site page or a non-dashboard context. Learn how to [initialize the workspace host](https://dev.wix.com/docs/sdk/host-modules/workspace/introduction.md).
- **The specified provider key is invalid or not found.**
The `providerKey` value doesn't match any supported provider. Check that you're using an exact value from the `providerKey` column in the [Available providers](#available-providers) table, including the app ID prefix.