agentleFS
remix-runremix-run/remix-store/.agents/skills/hydrogen-collection-browser/SKILL.md

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

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
  1. Distinctive:

    Use this skill for:

    line 18
  2. Distinctive:

    Search-result pages that reuse collection browse state.

    line 24
  3. Very specific:

    Before building UI, check whether this skill has a reference file for the app's framework in references/.

    line 28
  4. Very specific:

    If there is no matching reference, use createCollectionStore plus the …

    line 30
  5. Very specific:

    Use parseCollectionParams(searchParams) before Storefront API queries.

    line 43
  6. Distinctive:

    Use the framework binding when a matching reference exists.

    line 47
  7. Very specific:

    Use isFilterInputActive(state.filters, value.input) to mark checked filter inputs.

    line 59
  8. Distinctive:

    Treat availability and other single-choice filters as mutually exclusive when the Storefront filter input serializes to the same param name.

    line 62
  9. Very specific:

    Keep the search term in q.

    line 66
  10. Very specific:

    Use a collection handle like search:${term} so a new term rebuilds the browse store and does not carry old filters.

    line 67
  11. Very specific:

    Keep q as a hidden input inside the filter/sort form.

    line 68
  12. Distinctive:

    Do not use router query objects when filter param names contain dots, unless the framework preserves dotted keys literally.

    line 75
  13. Distinctive:

    Do not compute filter URLs manually when Hydrogen helpers can serialize/remove filters.

    line 76
  14. Very specific:

    Do not write a custom mapping table from ProductFilter shapes to URL params.

    line 77
  15. Very specific:

    Do not synthesize Storefront API ProductFilter objects from display metadata.

    line 78
  16. Distinctive:

    Do not store products in the collection store.

    line 79
  17. Very specific:

    Do not clear non-filter params such as q, campaign params, or variant params unless the route explicitly owns them.

    line 80
  18. Very specific:

    Search filters preserve q.

    line 94

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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 /search routes.
  • 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, or search:${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 from products.filters or search.productFilters.
  • currencyCode for PRICE_RANGE inputs, loaded by the same query as the products so it matches product prices: localization.country.currency.isoCode under @inContext in market-aware stores, or shop.paymentSettings.currencyCode in single-currency stores.
  • Optional totalCount and pageInfo for 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 explicit action (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 set method or action — so render both literally; the helper cannot infer the route.
  • Choose controls at the filter-group level: PRICE_RANGE renders min/max number inputs; LIST and BOOLEAN render 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 fixed filter.v.price.gte and filter.v.price.lte names for range inputs; continue deriving checkbox names and values from value.input.
  • Use formProps() on the browse form: spread it, then add the literal method="get" and action. 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 schedule form.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 while state.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 with formatMoney({ amount: "0", currencyCode }, { locale }).currencyNarrowSymbol and an explicit, stable locale (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 of CA$ or A$), so the accessible label carries the currency code. Do not add a separate Intl.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 an aria-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 noscript submit 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 before and after whenever 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 with getFilterRemovalUrl(...).
  • Use isFilterInputActive(state.filters, value.input) to mark checked filter inputs.
  • Treat each Storefront API FilterValue.input JSON string as the authoritative filter identity. To render one checkbox, parse that JSON into a ProductFilter, wrap it as { filters: [filter], sortKey: undefined, reverse: false }, and pass it to serializeCollectionParams(...) 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-compatible sort_by strings that parseCollectionParams() 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 q as a hidden input inside the filter/sort form.
  • Map unsupported search sorts back to RELEVANCE; only PRICE uses reverse.
  • 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; add key={term} so navigation (e.g. "Clear search" → /search) resets it. Safe because term changes only on submit/navigation, not while typing — do not put key={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 ProductFilter shapes to URL params. serializeCollectionParams(...) already maps supported shapes such as available, productType, productVendor, tag, variantOption, product metafields, variant metafields, and price into Liquid-compatible params.
  • Do not synthesize Storefront API ProductFilter objects from display metadata. value.input already 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_RANGE min/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.5 apply, and the URL carries only numeric filter.v.price.gte/filter.v.price.lte values, 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.