Collections & filtering

My <storesynk-collection> grid, filters, or sort show nothing

Everything in this subsystem consumes collectionContext from <storesynk-collection>. A <product-list>, <change-sort>, <change-filter>, <filter-list>, <change-price>, <active-filter-list>, <clear-filters>, <load-more>, or <show-result-count> placed outside a <storesynk-collection> has no context and renders nothing, silently (SSK-110). Keep the whole subsystem inside one <storesynk-collection>. (This is separate from <storesynk-list> - don’t mix the two; storesynk-list provides no collectionContext.)

The product grid stays empty even though the collection exists

<product-list> is a template-clone container: its first element child is the card template (must be, or contain, a <storesynk-product> with no handle/id - it’s fed via provideProduct()). With no such template there’s nothing to clone (SSK-107). Also confirm the handle on <storesynk-collection> matches a real collection - a missing one logs a console error and flips the grid to [ss-empty]. For a whole-store grid, leave handle empty - the engine lists the whole catalog via a wildcard search query (catalog mode), so no “all” collection needs to exist (this version onward; older engines fell back to all-handle="all"). Only set all-handle="…" when you have a curated all-products collection that sorts/merchandises better. Catalog mode caveat: the search connection only sorts by RELEVANCE/PRICE; other change-sort keys fall back to the default order.

My whole-store grid (/collections/all) is empty

You no longer need an all collection: with handle empty and no all-handle, <storesynk-collection> lists the whole catalog via wildcard search (catalog mode). If it’s still empty, products aren’t published to the Headless/Storefront sales channel (catalog mode only sees published products - see setup). If you’re on an older engine (before this version), catalog mode didn’t exist - either upgrade, create an all collection, or set all-handle to a real all-products collection (an automated collection with condition “price ≥ 0” includes everything).

Size / Product type / Vendor filter sections are empty (but the grid has products)

Facets come exclusively from the merchant’s Search & Discovery app filter configuration (Shopify admin → Search & Discovery → Filters), not from the product data itself - the Storefront API only returns the facets that app has enabled. So a store with vendors/types on its products still returns no vendor/type facet until those filters are turned on in Search & Discovery. Each facet section self-hides via [ss-empty] until its facet exists, so nothing is broken - the sections just stay hidden. Verify by running a direct productFilters query (or checking the Search & Discovery filter list); if the facet isn’t there, enable it in the app.

The filter checkboxes / facet groups never appear

<filter-list> clones its first <filter-group>, and the <filter-value> inside it is the per-value template - you need both or there’s nothing to clone (SSK-107). It renders one group per LIST facet Shopify returns; if no facets appear, the collection has no Search & Discovery filters configured, or every facet value has a zero count for the current results. Price is deliberately skipped - render it with <change-price>. To style one facet specially, pull it out into a <change-filter for="…"> and add its key to filter-list’s except.

<filter-value> / <show-filter-*> render nothing

These facet parts don’t consume context - their container writes their text - so they only work inside a filter container (SSK-108): filter-value and show-filter-label/-count/-swatch inside a <filter-list> or <change-filter>; show-filter-title also works inside an <active-filter-list> chip; filter-group only inside filter-list; active-filter-item only inside active-filter-list. <show-filter-swatch> only paints inside a <change-filter> (that’s the one that reads the value’s swatch color/image).

A hidden (.sr-only) filter title / swatch name becomes visible after hydration

You put a class like Tailwind’s .sr-only on a <show-filter-title> (or another invisible-registered holder - show-locale-name, show-option-title, etc.) to keep a swatch’s color name available to screen readers, and it showed up visually once the runtime loaded. The invisible parts apply display:contents for layout transparency, and display:contents dissolves the element’s box, which defeats box-based hiding like .sr-only’s 1px/clip. Fixed this version: display:contents is now applied only when the element is unstyled (no class, no inline display) - an authored class means you own its rendering, so your .sr-only wins. If you’re on an older engine, wrap the visually-hidden text in a plain <span class="sr-only"> inside the holder instead of styling the holder itself.

<clear-filters> / <load-more> are always hidden (or never hide)

Both use [ss-empty] as their visibility hook: clear-filters sets it when no filters are applied, load-more when there are no more pages. Hide them with CSS keyed off [ss-empty] (e.g. load-more[ss-empty] { display: none }), rather than expecting them to remove themselves. load-more also reflects [ss-loading] mid-fetch. For infinite scroll, drop <load-more> and add infinite to <storesynk-collection>.

Filters don’t persist in the URL / two collections clobber each other’s params

<storesynk-collection> mirrors filter/sort/page state into the URL by default. Add no-url-sync to opt out. With more than one collection on a page, give each a unique url-key (e.g. url-key="a") so their params are namespaced (a.color=…); without it, URL sync self-disables on the extra collections (they’d otherwise overwrite each other) and logs a console warning.

Result count flashes to 0 / facets vanish / the grid clears right after load (SSR)

On a server-rendered listing (<StoresynkCollection> / renderCollectionListing), the grid/facets/count were painted server-side but blanked for a moment on hydration. Fixed this version onward: the data-storesynk-listing payload now seeds engine state even when a mismatch (URL-restored filters/sort/page, or a locale mismatch) forces a client refetch - so the count, facets, and grid hold the server render under [ss-loading] instead of collapsing to a phantom-empty state until the fetch lands. If you still see it, you’re on an older engine, or the region isn’t actually being server-rendered (the host has no ss-adopt / no data-storesynk-listing child - confirm the wrapper rendered, not the plain client fallback).

The grid dims ([ss-loading]) briefly after load for a locale-switched buyer (SSR)

The server rendered the listing in the buyer’s market, but the client refetched anyway on hydration (a brief dim). Fixed this version: the listing payload’s locale stamp is the authority and now supersedes the store’s revalidateAdopted flag - a page the server already rendered for THIS buyer’s market adopts without refetching. This requires the route to actually thread the buyer market: read it (getRequestLocale()) and pass it as locale to <StoresynkCollection> (and to getCollectionListing) so the server renders - and stamps - the same market the client reads from the storesynk_locale cookie. If the stamps disagree, the client sees a mismatch and refetches.

Duplicate filter rows (e.g. “Availability” appears three times) (SSR)

A server-rendered facet group carries one filled <filter-value> clone per value; on the first client re-render the old engine only removed the placeholder, leaving the server clones behind under the fresh ones. Fixed this version: filter-list now clears every <filter-value> from a cloned group before re-rendering. If you still see duplicates, upgrade the engine.

---

Imported from the Storesynk skill v0.1.0 (references/known-issues.md). To change this page, change it there.