Reference Picker

The Reference Picker is a search dialog that appears when you edit a metafield whose type references another Shopify resource. For example, a "Related Product" metafield of type product_reference uses this picker to let you search for and select the target product.

When It Appears

The Reference Picker opens when you:

  • Edit a reference-type metafield on a product or variant
  • Set a value for a list reference metafield (e.g., multiple related products)
  • Work with mixed reference metafields that can link to different resource types

Supported Reference Types

Reference Type What You Can Select Search By
Product Products in your store Title, handle, or vendor
Variant Product variants Product title, variant name, SKU, or barcode
Collection Collections Collection title
Page Shopify pages Page title or handle
File Uploaded files and images Filename or alt text
Metaobject Custom metaobject entries Display name
Mixed Any of the above Depends on selected type

How to Use

Searching

  1. Type your search term in the search box at the top of the dialog
  2. Results appear automatically as you type
  3. For Products, Variants, and Collections, results filter from your local cache instantly
  4. For Pages, Files, and Metaobjects, results are fetched from Shopify after a brief pause

Selecting a Single Item

  1. Search for the resource you need
  2. Click a row to select it (it highlights)
  3. Click Select to confirm your choice

Selecting Multiple Items

When the metafield is a list type (e.g., list.product_reference), multi-select mode is active:

  1. Search for resources
  2. Click rows to toggle them in or out of your selection
  3. Selected items appear in a summary area
  4. Click the remove button next to any selected item to deselect it
  5. Click Select to confirm all chosen items

Loading More Results

Results load in pages. If more results are available, a status message indicates this. Click Load More to fetch the next page.

Mixed Reference Mode

Some metafields use the mixed_reference type, which allows linking to different kinds of resources. When editing these:

  1. A type selector dropdown appears at the top of the dialog
  2. Choose the resource type you want to browse (Product, Variant, Collection, Page, File, or Metaobject)
  3. The search results and column layout update to match the selected type
  4. Search and select as normal

Switching types clears the current search text and results.

Metaobject References

When a metafield references a specific metaobject type (e.g., "Size Chart" or "Material"), the picker is constrained to that type:

  • Only entries of the matching metaobject type are shown
  • Initial results load automatically without requiring a search term
  • You can still search by display name to filter the list

In mixed reference mode, each metaobject type defined in your store appears as a separate option in the type selector dropdown (e.g., "Metaobject: Size Chart", "Metaobject: Material").

Note: Metaobject access requires the read_metaobjects API scope. If this scope is not configured on your custom app, a warning message will appear instead of results. Update your app permissions in Shopify Admin and reconnect to resolve this.

Result Columns

The information displayed varies by resource type:

Type Columns Shown
Product Image, Title, Handle, Status
Variant Product title, Variant name, SKU, Price
Collection Image, Title, Handle, Product count
Page Title, Handle, Created date
File Image/icon, Filename, File type, Status, Size
Metaobject Image, Display name, Handle, Type, Updated date

Tips

  • Minimum search length: For Pages, Files, and Metaobjects, type at least 2 characters before results appear. Products, Variants, and Collections filter from cache and respond to any input.
  • Results are cached: Repeated searches for the same term return instantly from the session cache.
  • Page size: Results load in batches of 50. Use the Load More button to see additional results.
  • Variant scoping: When editing a variant reference metafield on a specific product, the picker may be scoped to show only that product's variants.
  • Cancel to discard: Click Cancel or press Escape to close the picker without changing the metafield value.

See Also