Skip to content

feat(hydrogen): add CollectionView for the shopify:collection:view event - #4386

Open
Ji-One1 wants to merge 1 commit into
jb/hydrogen-product-view-appsfrom
jb/hydrogen-collection-view-event
Open

Ji-One1 wants to merge 1 commit into
jb/hydrogen-product-view-appsfrom
jb/hydrogen-collection-view-event

Conversation

@Ji-One1

@Ji-One1 Ji-One1 commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Stacked on #4403. Refs Shopify/developer-tools-team#1285

Part 3 of 4. This PR adds the package API only. The template and examples use it in the next PR (#4404).

TL;DR: Adds CollectionView, a component that sends the shopify:collection:view Standard Event when a collection page shows. It works like ProductView from #4376: it uses createViewEventElement from the Standard Events module, and the storefront places it explicitly.

Before

Hydrogen has no way to send a collection view event.

After

<CollectionView collection={collection} productsCount={products.length} className="block">
  <ProductGrid products={products} />
</CollectionView>

The element sends:

{ collection: { id, handle, productsCount } }

What this changes

  • CollectionView (React and Vue) renders a shopify-collection-view element, registered with defineViewEventElement() from feat(hydrogen): add ProductView for the shopify:product:view event #4376. The element sends the event from itself when it appears, and the event bubbles to document.
  • The element is Hydrogen's subclass of the createViewEventElement() class (the same helper as the product view element). It sends the event again when the collection handle in view-event-payload changes, for example on in-app navigation to another collection. The React and Vue CollectionView components only render the element. Filter, sort, and "load more" changes don't send it. Those belong to shopify:collection:update, which is not in this PR.
  • ShopifyScripts and initializeShopifyScripts() register the element, next to the product view element.
  • collection.id is required (string | null), so a query that forgets id fails typechecking. Pass id: null for a page without a collection record, such as an all-products page.
  • Frameworks without a Hydrogen binding (Solid, Svelte) render COLLECTION_VIEW_TAG_NAME with the attributes from getCollectionViewAttributes().
  • React CollectionView maps className to the custom element's class attribute, so grid and block classes work in React 18 as well as React 19.
  • The analytics and collection browser skills explain where to put CollectionView.

Developer impact

Includes a minor changeset for @shopify/hydrogen. New exports:

  • @shopify/hydrogen/react and @shopify/hydrogen/vue: CollectionView, CollectionViewProps.
  • @shopify/hydrogen: COLLECTION_VIEW_TAG_NAME, getCollectionViewAttributes, defineCollectionView, CollectionViewOptions.

Hydrogen doesn't send the event on its own. Storefronts add CollectionView to their collection page.

productsCount is the number of products that the page loaded, not the collection total. The Storefront API has no direct product count on Collection or collection.products. The storefront passes the loaded count explicitly, so Hydrogen doesn't guess. We asked the Standard Events owners whether productsCount can be optional, or what headless storefronts should send.

Why we don't sum availability filter counts

We considered adding the in-stock and out-of-stock filter counts to get the collection total, but read-only Storefront API 2026-10 queries on hydrogen-preview.myshopify.com, collection backcountry, disproved that approach:

Query Unique products Availability counts
No filters 26 25 + 6 = 31
binding mount=Nested 2 2 + 2 = 4

We checked all product pages and both availability groups. Five products appeared in both groups, so adding the counts double-counted them. The other filter also changed the counts. Using an unfiltered query would not fix the overlap. The individual availability counts matched their query results; the sum was not a unique product total. So we don't recommend that shortcut and keep the loaded-product count instead.

Out of scope

Risk

  • productsCount is lower than the real total for any collection with more than one page.
  • Tests run under React 19 only. React CollectionView maps className to class explicitly so React 18 keeps CSS classes, but it was not run under a React 18 runtime.

How to Test

This PR has no storefront wiring. To try it in a browser, check out the next PR (#4404) and follow its steps.

@Ji-One1
Ji-One1 marked this pull request as ready for review November 17, 2026 19:15
@Ji-One1
Ji-One1 requested a review from a team as a code owner November 17, 2026 19:15
@Ji-One1
Ji-One1 marked this pull request as draft November 18, 2026 06:18
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-product-view-event branch from 51c0a2b to bccc8da Compare November 18, 2026 16:21
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-collection-view-event branch 4 times, most recently from 7c4a388 to 3b6b749 Compare November 19, 2026 20:53
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-product-view-event branch from 15d022f to e41554b Compare November 19, 2026 21:04
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-collection-view-event branch from 3b6b749 to 818bcb5 Compare November 19, 2026 21:04
@Ji-One1
Ji-One1 changed the base branch from jb/hydrogen-product-view-event to jb/hydrogen-product-view-apps November 19, 2026 22:26
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-collection-view-event branch from 818bcb5 to 449faec Compare November 19, 2026 22:27
@Ji-One1
Ji-One1 marked this pull request as ready for review November 20, 2026 05:41
CollectionView (React, Vue) renders the shopify-collection-view element,
registered via defineViewEventElement(). The element sends
shopify:collection:view from itself when the collection page connects,
and again when collection.handle in view-event-payload changes. Filter,
sort, pagination, and productsCount changes don't re-send it.

The Storefront API has no product total for a collection, so the
storefront passes productsCount (the number of products loaded on the
page). collection.id is required (string | null) so queries missing id
fail typechecking. ShopifyScripts and initializeShopifyScripts register
the element. Frameworks without a binding use COLLECTION_VIEW_TAG_NAME
and getCollectionViewAttributes.
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-product-view-apps branch from d8bc01a to d2fbef4 Compare November 20, 2026 06:24
@Ji-One1
Ji-One1 force-pushed the jb/hydrogen-collection-view-event branch from 449faec to 1b06680 Compare November 20, 2026 06:24

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant