shopify-context
component

The context component defines which Shopify data should be available in different parts of your page.

Each <shopify-context> component requires two attributes:

type: Specifies what kind of data you want (for example, product).
handle or gid: Identifies the specific item. For example, the handle for the URL demostore.mock.shop/products/men-t-shirt is men-t-shirt. The gid attribute can be used to identify the item by its unique id, e.g. gid://shopify/Product/7982853619734.

If you're working with a single storefront, then you can add the <shopify-context> component anywhere on your page (it doesn't need to be inside the <shopify-store> component). If you're working with multiple storefronts, then nest the context inside its corresponding store component.

Every <shopify-context> component also requires a <template> component, which contains the data you want to display. That template won't be rendered until the context is loaded. Render placeholder content outside the template with an attribute shopify-loading-placeholder. This content will be displayed until the context is loaded.

See the playground for complete examples.

Anchor to attributesAttributes

Anchor to type type string required: The type of the context. This needs to match the GraphQL Storefront API type you are querying. For example, if you are querying a product, the type should be type="product".
Anchor to gid gid string: The unique id for the context. Required on some objects, like products, collections, and blogs, if the handle attribute isn't used.
Anchor to handle handle string: The handle for the context. Required on some objects, like products, collections, and blogs. The handle is required unless the wait-for-update attribute is included or the gid attribute is used instead.
Anchor to key key string: The key for the metafield. Required when the context type is metafield.
Anchor to metaobject-definition-type metaobject-definition-type string: The metaobject definition type for the context. Required when the context type is metaobject.
Anchor to namespace namespace string: The namespace for the metafield. Required when the context type is metafield.
Anchor to query query string: The query path for accessing nested data within a parent context.

Required when this context is nested inside another context. The query should specify the path to access the desired data from the parent.

Example: If the parent context is a product, and you want to access its first available variant: query="product.selectedOrFirstAvailableVariant"
Anchor to update update (e: Event) => void: Updates this context to match the data from another context of the same type.

Common use case: When displaying a list of products, you might want to show a detailed view of a single product in a modal. This method allows you to update the modal's context to display the selected product's data.

How it works:

The event target must be inside the source context you want to copy from

This context will update its handle to match the source context

The data will be automatically refreshed to show the new content
Anchor to wait-for-update wait-for-update boolean: Wait to render the context until the update method is called. This is useful for dynamically rendering a context.

ContextAttributes

gid
The unique id for the context. Required on some objects, like products, collections, and blogs, if the `handle` attribute isn't used.
```
string
```
handle
The handle for the context. Required on some objects, like products, collections, and blogs. The handle is required unless the `wait-for-update` attribute is included or the `gid` attribute is used instead.
```
string
```
key
The key for the metafield. Required when the context type is `metafield`.
```
string
```
metaobject-definition-type
The metaobject definition type for the context. Required when the context type is `metaobject`.
```
string
```
namespace
The namespace for the metafield. Required when the context type is `metafield`.
```
string
```
query
The query path for accessing nested data within a parent context. Required when this context is nested inside another context. The query should specify the path to access the desired data from the parent. Example: If the parent context is a product, and you want to access its first available variant: query="product.selectedOrFirstAvailableVariant"
```
string
```
type
The type of the context. This needs to match the [GraphQL Storefront API](https://shopify.dev/docs/api/storefront) type you are querying. For example, if you are querying a product, the type should be `type="product"`.
```
string
```
update
Updates this context to match the data from another context of the same type. Common use case: When displaying a list of products, you might want to show a detailed view of a single product in a modal. This method allows you to update the modal's context to display the selected product's data. How it works: 1. The event target must be inside the source context you want to copy from 2. This context will update its handle to match the source context 3. The data will be automatically refreshed to show the new content
```
(e: Event) => void
```
wait-for-update
Wait to render the context until the update method is called. This is useful for dynamically rendering a context.
```
boolean
```

interface ContextAttributes extends BaseContextAttributes {
  /**
   * The query path for accessing nested data within a parent context.
   *
   * Required when this context is nested inside another context. The query should specify
   * the path to access the desired data from the parent.
   *
   * Example:
   * If the parent context is a product, and you want to access its first available variant:
   * query="product.selectedOrFirstAvailableVariant"
   */
  query?: string;

  /**
   * The handle for the context. Required on some objects, like products, collections, and blogs. The handle is required unless the `wait-for-update` attribute is included or the `gid` attribute is used instead.
   */
  handle?: string;

  /**
   * The unique id for the context. Required on some objects, like products, collections, and blogs, if the `handle` attribute isn't used.
   */
  gid?: string;

  /**
   * Updates this context to match the data from another context of the same type.
   *
   * Common use case: When displaying a list of products, you might want to show
   * a detailed view of a single product in a modal. This method allows you to
   * update the modal's context to display the selected product's data.
   *
   * How it works:
   *
   * 1. The event target must be inside the source context you want to copy from
   *
   * 2. This context will update its handle to match the source context
   *
   * 3. The data will be automatically refreshed to show the new content
   *
   * @param event - The event object whose target is a descendant element of the source context
   */
  update?: (e: Event) => void;

  /**
   * The namespace for the metafield. Required when the context type is `metafield`.
   */
  namespace?: string;

  /**
   * The key for the metafield. Required when the context type is `metafield`.
   */
  key?: string;

  /**
   * Wait to render the context until the update method is called. This is useful for dynamically rendering a context.
   */
  "wait-for-update"?: boolean;
}

Was this section helpful?

Example

HTML

<shopify-store

store-domain="https://your-store.myshopify.com"

</shopify-store>

<shopify-context

type="product"

handle="handle-of-product"

<!-- The data component is bound to the product

context and queries the title field -->

<h1>

<shopify-data

query="product.title"

></shopify-data>

</h1>

</template>

<!-- Render placeholder content

until the context is loaded -->

<div shopify-loading-placeholder>Loading...</div>

</shopify-context>

examples

example

description

This is the default example

HTML

<shopify-store
  store-domain="https://your-store.myshopify.com"
>
</shopify-store>

<!-- The context is bound to the store -->
<shopify-context
  type="product"
  handle="handle-of-product"
>
  <template>
    <!-- The data component is bound to the product
     context and queries the title field -->
    <h1>
      <shopify-data
        query="product.title"
      ></shopify-data>
    </h1>
  </template>
  <!-- Render placeholder content
   until the context is loaded -->
  <div shopify-loading-placeholder>Loading...</div>
</shopify-context>

Anchor to examplesExamples

Examples of various ways to use the <shopify-context> component.

Anchor to example-updating-a-context-with-a-dialogUpdating a context with a dialog

Show a list of products, and clicking each product opens a dialog with product details

Anchor to example-paginated-list-of-productsPaginated list of products

Show a list of products, and clicking the next and previous buttons loads the next and previous pages of products

Anchor to example-metafield-valueMetafield value

Show a metafield value

Anchor to example-metafield-referenceMetafield reference

Use a metafield to reference a single product

Anchor to example-metafield-list-referencesMetafield list references

Use a metafield to references a list of products

Anchor to example-metaobjectMetaobject

Render a metaobject context with a text field and a reference media field

Was this section helpful?

Updating a context with a dialog

HTML

<shopify-store

store-domain="https://your-store.myshopify.com"

country="CA"

language="FR"

</shopify-store>

function showProductDetails(event) {

// Update a dialog context with a selected product

document.getElementById('dialog-context')

.update(event);

// Show the dialog

document.getElementById('dialog')

.showModal();

}

</script>

<shopify-list-context

type="product"

query="products"

first="10"

<button

onclick="showProductDetails(event)"

<shopify-data

query="product.title"

></shopify-data>

</button>

</template>

</shopify-list-context>

<shopify-context

id="dialog-context"

type="product"

wait-for-update

<div>

<shopify-data

query="product.description"

></shopify-data>

</div>

</template>

<div

shopify-loading-placeholder

</div>

</shopify-context>

</dialog>

examples

Updating a context with a dialog

description

Show a list of products, and clicking each product opens a dialog with product details

HTML

<shopify-store
  store-domain="https://your-store.myshopify.com"
  country="CA"
  language="FR"
>
</shopify-store>

<script>
  function showProductDetails(event) {
    // Update a dialog context with a selected product
    document.getElementById('dialog-context')
      .update(event);

    // Show the dialog
    document.getElementById('dialog')
      .showModal();
  }
</script>

<shopify-list-context
  type="product"
  query="products"
  first="10"
>
  <!-- This template is repeated for each product-->
  <template>
    <button
      onclick="showProductDetails(event)"
    >
      <shopify-data
        query="product.title"
      ></shopify-data>
    </button>
  </template>
</shopify-list-context>

<dialog id="dialog">
  <shopify-context
    id="dialog-context"
    type="product"
    wait-for-update
  >
    <template>
      <div>
        <shopify-data
          query="product.description"
        ></shopify-data>
      </div>
    </template>
    <div
      shopify-loading-placeholder
    >
      Loading...
    </div>
  </shopify-context>
</dialog>

Paginated list of products

description

Show a list of products, and clicking the next and previous buttons loads the next and previous pages of products

HTML

<shopify-store
  store-domain="https://your-store.myshopify.com"
  country="CA"
  language="FR"
>
</shopify-store>

<shopify-list-context
  type="product"
  query="products"
  first="10"
>
  <!-- This template is repeated for each product-->
  <template>
    <shopify-data
      query="product.title"
    ></shopify-data>
  </template>
</shopify-list-context>
<button
  id="previous"
  onclick="getElementById('list-context').previousPage();"
>
  Previous
</button>
<button
  id="next"
  onclick="getElementById('list-context').nextPage();"
>
  Next
</button>

<script>
  // Listen for the list context to update
  // and disable the next and previous buttons when 
  // the list is at the end or beginning
  document
    .querySelector("shopify-context")
    .addEventListener(
      "shopify-list-context-update",
      (event) => {
        const {
          hasNextPage,
          hasPreviousPage,
        } = event.detail;
        if (!hasNextPage) {
          document
            .getElementById("next")
            .setAttribute(
              "disabled",
              "true",
            );
        } else {
          document
            .getElementById("next")
            .removeAttribute("disabled");
        }
        if (!hasPreviousPage) {
          document
            .getElementById("previous")
            ?.setAttribute(
              "disabled",
              "true",
            );
        } else {
          document
            .getElementById("previous")
            .removeAttribute("disabled");
        }
      },
    );
</script>

Metafield value

description

Show a metafield value

HTML

<shopify-store
  store-domain="https://your-store.myshopify.com"
>
</shopify-store>

<shopify-context
  type="product"
  handle="your-product-handle"
>
  <template>
    <shopify-context
      type="metafield"
      query="product.metafield"
      key="your_metafield_key"
      namespace="your_metafield_namespace"
    >
      <template>
        <div>
          <shopify-data
            query="metafield.value"
          ></shopify-data>
        </div>
      </template>
    </shopify-context>
  </template>
</shopify-context>

Metafield reference

description

Use a metafield to reference a single product

HTML

<shopify-store
  store-domain="https://your-store.com"
>
</shopify-store>

<shopify-context
  type="product"
  handle="your-product-handle"
>
  <template>
    <!-- Setup a context for the metafield -->
    <shopify-context
      type="metafield"
      key="related_products"
      key="your_metafield_key"
      namespace="your_metafield_namespace"
    >
      <template>
        <!-- Setup a new context for the metafield reference -->
        <shopify-context
          type="product"
          query="metafield.reference"
        >
          <template>
            <div>
              <!-- Render the title of the metafield reference -->
              <shopify-data
                query="product.title"
              ></shopify-data>
            </div>
          </template>
        </shopify-context>
      </template>
    </shopify-context>
  </template>
</shopify-context>

Metafield list references

description

Use a metafield to references a list of products

HTML

<shopify-store
  store-domain="https://your-store.com"
>
</shopify-store>

<shopify-context
  type="product"
  handle="your-product-handle"
>
  <template>
    <!-- Setup a context for the metafield -->
    <shopify-context
      type="metafield"
      key="related_products"
      key="your_metafield_key"
      namespace="your_metafield_namespace"
    >
      <template>
        <!-- Setup a list context for the metafield references -->
        <shopify-list-context
          type="product"
          query="metafield.references"
          first="5"
        >
          <template>
            <div>
              <shopify-data
                query="product.title"
              ></shopify-data>
            </div>
          </template>
        </shopify-list-context>
      </template>
    </shopify-context>
  </template>
</shopify-context>

Metaobject

description

Render a metaobject context with a text field and a reference media field

HTML

<!-- pass the name of the metaobject as an attribute -->
<shopify-context
  type="metaobject"
  handle="toronto"
  metaobject-definition-type="stores"
>
  <template>
    <!-- render a field on the metaobject -->
    <h1>
      <shopify-context
        type="field"
        query="metaobject.field"
        key="title"
      >
        <template>
          <shopify-data
            query="field.value"
          ></shopify-data>
        </template>
      </shopify-context>
    </h1>

    <!-- render a reference field on the metaobject -->
    <p>
      <shopify-context
        type="field"
        query="metaobject.field"
        key="featured_image"
      >
        <template>
          <shopify-context
            type="media"
            query="field.reference"
          >
            <template>
              <shopify-media
                query="media"
                width="100"
                height="100"
              ></shopify-media>
            </template>
          </shopify-context>
        </template>
      </shopify-context>
    </p>
  </template>
</shopify-context>

Anchor to relatedRelated

shopify-list-context

shopify-contextcomponent

Anchor to attributesAttributes

ContextAttributes

examples

example

description

HTML

Anchor to examplesExamples

examples

Updating a context with a dialog

description

HTML

Paginated list of products

description

HTML

Metafield value

description

HTML

Metafield reference

description

HTML

Metafield list references

description

HTML

Metaobject

description

HTML

Anchor to relatedRelated

shopify-context
component