hydrogen-collection-browser
Skill218 starsChanged 10 days agoMITView on GitHub
Guide for building collection and search browsing UI with @shopify/hydrogen. Use when creating, modifying, or reviewing collection routes, search results, product grids, filters, sort controls, active filter chips, or URL-synced browse state in storefront frameworks.
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- Shopify/hydrogenedited, first seen Oct 13, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- Shopify/hydrogen★ 2.2k90% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- hydrogen-analyticsSkill
- hydrogen-cart-drawerSkill
- hydrogen-cart-metafieldsSkill
- hydrogen-cart-uiSkill
- hydrogen-customer-accountSkill
- hydrogen-imageSkill
- hydrogen-local-httpsSkill
- hydrogen-marketsSkill
- hydrogen-moneySkill
- hydrogen-oxygenSkill
- hydrogen-predictive-searchSkill
- hydrogen-request-handlersSkill
- hydrogen-routingSkill
- hydrogen-setupSkill
- hydrogen-shop-paySkill
- hydrogen-smoke-testSkill
- hydrogen-storefront-clientSkill
- hydrogen-variant-formSkill
- remix-storeSkill
- testing-practicesSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 7 are distinctive, and 11 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 18
Use this skill for:
- Distinctive: line 24
Search-result pages that reuse collection browse state.
- Very specific: line 28
Before building UI, check whether this skill has a reference file for the app's framework in references/.
- Very specific: line 30
If there is no matching reference, use createCollectionStore plus the …
- Very specific: line 43
Use parseCollectionParams(searchParams) before Storefront API queries.
- Distinctive: line 47
Use the framework binding when a matching reference exists.
- Very specific: line 59
Use isFilterInputActive(state.filters, value.input) to mark checked filter inputs.
- Distinctive: line 62
Treat availability and other single-choice filters as mutually exclusive when the Storefront filter input serializes to the same param name.
- Very specific: line 66
Keep the search term in q.
- Very specific: line 67
Use a collection handle like search:${term} so a new term rebuilds the browse store and does not carry old filters.
- Very specific: line 68
Keep q as a hidden input inside the filter/sort form.
- Distinctive: line 75
Do not use router query objects when filter param names contain dots, unless the framework preserves dotted keys literally.
- Distinctive: line 76
Do not compute filter URLs manually when Hydrogen helpers can serialize/remove filters.
- Very specific: line 77
Do not write a custom mapping table from ProductFilter shapes to URL params.
- Very specific: line 78
Do not synthesize Storefront API ProductFilter objects from display metadata.
- Distinctive: line 79
Do not store products in the collection store.
- Very specific: line 80
Do not clear non-filter params such as q, campaign params, or variant params unless the route explicitly owns them.
- Very specific: line 94
Search filters preserve q.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Collection And Search Browsing
Hydrogen's collection primitive manages browse intent: filters, sort, URL params, and loading status. It does not own product data. The framework loader/server component owns Storefront API queries and passes products plus available filters into UI.
Use this skill for:
/collections,/collections/:handle, and/searchroutes.- Product grid filtering and sorting.
- Active filter chips and clear links.
- No-JS GET form fallbacks for filters and sort.
- Search-result pages that reuse collection browse state.
Framework References
Before building UI, check whether this skill has a reference file for the app's framework in references/. If one exists, read it and use that framework binding or route pattern first.
If there is no matching reference, use createCollectionStore plus the parseCollectionParams/serializeCollectionParams/getFilterRemovalUrl/isFilterInputActive helpers from @shopify/hydrogen directly, and apply the UI and search rules below with the framework's own form, route, and reactivity primitives.
Data Contract
Server data should include:
- Collection/search identity: collection
handle, orsearch:${term}for search pages. dataSearch: the exact search string used for the server query.products: Storefront API product nodes shaped for the product card.availableFilters: normalized filter metadata fromproducts.filtersorsearch.productFilters.currencyCodeforPRICE_RANGEinputs, loaded by the same query as the products so it matches product prices:localization.country.currency.isoCodeunder@inContextin market-aware stores, orshop.paymentSettings.currencyCodein single-currency stores.- Optional
totalCountandpageInfofor search or pagination UI.
Use parseCollectionParams(searchParams) before Storefront API queries. Pass parsed filters, sortKey, and reverse into collection.products(...) or search(...).
UI Rules
- Use the framework binding when a matching reference exists. Otherwise, use the core store directly. Do not hand-roll browse state with component state.
- The browse form must carry both
method="get"and an explicitaction(the collection/search route URL, e.g.action="/collections/shoes"or the search route) so filters and sort degrade to a real GET submit without JavaScript.formProps()only wires the submit handler — it does not setmethodoraction— so render both literally; the helper cannot infer the route. - Choose controls at the filter-group level:
PRICE_RANGErenders min/max number inputs;LISTandBOOLEANrender value checkboxes. A price value serializes to two params, so never use the number of serialized entries to decide whether to render the group. Use the fixedfilter.v.price.gteandfilter.v.price.ltenames for range inputs; continue deriving checkbox names and values fromvalue.input. - Use
formProps()on the browse form: spread it, then add the literalmethod="get"andaction. Submit checkboxes and<select>controls immediately on change. Submit price inputs on change with a 350 ms debounce: share one timer between the min and max inputs, clear any pending timer before you scheduleform.requestSubmit(), and clear the timer on unmount. Update the mounted price inputs in place when bounds change externally, and cancel pending drafts on deliberate navigation. Keep newer typing when the URL update from the shopper's own price submission arrives. Preserve native Enter and form keyboard behavior. Cancel the pending timer whenever the form submits, so each submission sends one request. - Keep every filter control (checkboxes, sort
<select>, price inputs) mounted and enabled whilestate.status === "loading", and show loading with a pending visual state. Keep stable keys based on control identity across filter updates, so the focused control stays in the DOM. Update external changes (chips, clear-all, back/forward) in place by binding checked and selected values to browse state. Keep native keyboard activation, such as Space on checkboxes and arrow keys on the<select>. Focus can still be lost if a result update removes the focused option, for example when zero-count options are hidden. - Make price inputs currency-aware with the explicit server
currencyCode. Get the prefix withformatMoney({ amount: "0", currencyCode }, { locale }).currencyNarrowSymboland an explicit, stablelocale(the resolved market locale, or one fixed locale in single-market stores) so server and client render the same symbol. The narrow symbol drops currency qualifiers ($for USD, CAD, and AUD instead ofCA$orA$), so the accessible label carries the currency code. Do not add a separateIntl.NumberFormat, hardcode$, infer the currency from the locale, or convert amounts. - Render each price input as
type="number",min="0",step="any"in a wrapper with the symbol as anaria-hidden="true"prefix. The symbol is not part of the input value or URL params; params carry plain numbers only (filter.v.price.gte=10.5). Give each input an accessible label with minimum or maximum and the currency code, e.g. "Minimum price in CAD". - Render a
noscriptsubmit button for filter sidebars that auto-submit when hydrated. - Render "load more" / pagination as a GET link (the framework's link component) carrying the next-page cursor (e.g.
?after=<endCursor>), so it works without JavaScript. Hydration may upgrade it to append-in-place; the bare link must still load the next page server-side (it replaces the page rather than appending when JS is off). - Clear both
beforeandafterwhenever filters or sorting change so the new browse state starts from its first page. - Show stale products with a pending visual state while
state.status === "loading"; do not replace the grid with a skeleton. - Serialize active filter chips from
serializeCollectionParams(state)and remove filters withgetFilterRemovalUrl(...). - Use
isFilterInputActive(state.filters, value.input)to mark checked filter inputs. - Treat each Storefront API
FilterValue.inputJSON string as the authoritative filter identity. To render one checkbox, parse that JSON into aProductFilter, wrap it as{ filters: [filter], sortKey: undefined, reverse: false }, and pass it toserializeCollectionParams(...)for the field name/value. Do not derive filter shapes or param names from filter IDs, labels, or types. - Build sort option values with
getSortByValue(...); it emits the Liquid-compatiblesort_bystrings thatparseCollectionParams()understands. - Treat availability and other single-choice filters as mutually exclusive when the Storefront filter input serializes to the same param name.
Search Rules
- Keep the search term in
q. - Use a collection handle like
search:${term}so a new term rebuilds the browse store and does not carry old filters. - Keep
qas a hidden input inside the filter/sort form. - Map unsupported search sorts back to
RELEVANCE; onlyPRICEusesreverse. - Empty search terms should return an empty product list and no filters rather than querying Storefront API.
- The search input is uncontrolled (
defaultValue={term}) so the no-JS GET submit works; addkey={term}so navigation (e.g. "Clear search" →/search) resets it. Safe becausetermchanges only on submit/navigation, not while typing — do not putkey={term}on a controlled input that updates the term per keystroke (focus loss).
Anti-Patterns
- Do not use router query objects when filter param names contain dots, unless the framework preserves dotted keys literally.
- Do not compute filter URLs manually when Hydrogen helpers can serialize/remove filters.
- Do not write a custom mapping table from
ProductFiltershapes to URL params.serializeCollectionParams(...)already maps supported shapes such asavailable,productType,productVendor,tag,variantOption, product metafields, variant metafields, and price into Liquid-compatible params. - Do not synthesize Storefront API
ProductFilterobjects from display metadata.value.inputalready contains the supported filter shape. - Do not store products in the collection store; products come from the framework data response.
- Do not clear non-filter params such as
q, campaign params, or variant params unless the route explicitly owns them.
Verify
- Filtering and sorting update the URL without scroll reset when hydrated.
- Checkbox filters and
PRICE_RANGEmin/max controls both render, apply, and persist after reloading the URL. - Price inputs show the narrow symbol for the loaded currency (e.g.
$for USD or CAD,€,¥), and the symbol does not change after hydration. - Decimal bounds such as
10.5apply, and the URL carries only numericfilter.v.price.gte/filter.v.price.ltevalues, with no symbol or currency code. - The symbol prefix and input stay aligned and usable at desktop and mobile widths.
- Accessible names identify minimum or maximum and the currency code; screen readers do not announce the symbol prefix.
- Reloading the filtered URL server-renders the same filtered state.
- With JavaScript disabled, checking filters and submitting the form loads the filtered URL.
- With JavaScript disabled, the load-more / pagination link loads the next page server-side.
- Active filter chips remove only one filter and preserve unrelated params.
- Search filters preserve
q. - Back/forward navigation settles loading state.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

