hydrogen-predictive-search
Skill218 starsChanged 10 days agoMITView on GitHub
Guide for building predictive search with @shopify/hydrogen. Use when adding, modifying, or reviewing autocomplete/search-as-you-type UI, predictive search route handlers, tracking URLs, custom predictive search fragments, or framework predictive search bindings.
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.2k82% 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-collection-browserSkill
- hydrogen-customer-accountSkill
- hydrogen-imageSkill
- hydrogen-local-httpsSkill
- hydrogen-marketsSkill
- hydrogen-moneySkill
- hydrogen-oxygenSkill
- 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
15 rules. About 0 are common, 8 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈8
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 23
Keep rendering app-owned. Hydrogen provides data, state, request lifecycle, and URL helpers — not a dropdown template.
- Distinctive: line 35
Use the same request-scoped Storefront client as the app's other Hydrogen handlers and loaders.
- Very specific: line 41
When building with a UI framework, check this skill's references/ directory for framework-specific instructions.
- Very specific: line 45
Use getPredictiveSearchItemUrl() for predictive result links.
- Very specific: line 58
If the storefront uses custom Shopify resource paths, use the local hydrogen-routing skill before wiring predictive search result URLs.
- Very specific: line 60
Use getSearchResultUrl() only when constructing a custom search-attributed URL that is not backed by a predictive search item.
- Distinctive: line 62
Do not publish a new analytics event for predictive suggestions.
- Distinctive: line 66
Use additive fragments when the UI needs extra result fields:
- Very specific: line 99
Use the route-handler form for browser-backed autocomplete.
- Distinctive: line 103
Use the packaged route handler as the default browser transport.
- Distinctive: line 105
Keep UI rendering and layout app-owned.
- Very specific: line 107
Use q for the search term so predictive and full search URLs align.
- Very specific: line 108
Use the local hydrogen-routing skill for result URLs when the app uses custom Shopify resource paths.
- Distinctive: line 110
Keep debounce in the client store.
- Distinctive: line 111
Prefer additive fragments over full query overrides.
≈ “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
Hydrogen Predictive Search
Hydrogen predictive search has four layers:
- Storefront API query helper in
@shopify/hydrogen. - Same-origin route handler at
/api/predictive-search. - Framework-neutral client store.
- Framework provider/hooks or composables.
Keep rendering app-owned. Hydrogen provides data, state, request lifecycle, and URL helpers — not a dropdown template.
Server Route
Register the packaged route handler in the app's central handleShopifyRoutes() wiring before framework routing. Use the hydrogen-request-handlers skill for the full framework-specific request context, session manager, and Storefront client setup.
import { createPredictiveSearchServerHandlers } from "@shopify/hydrogen";
const predictiveSearchHandlers = createPredictiveSearchServerHandlers();Use the same request-scoped Storefront client as the app's other Hydrogen handlers and loaders. Do not create a second client inside predictive search code.
The default browser predictive search endpoint is GET /api/predictive-search. Override it with predictiveSearchEndpoint when the JSON route lives elsewhere. The route accepts q plus optional Storefront API controls such as limit, limitScope, types, searchableFields, and unavailableProducts.
Framework UI
When building with a UI framework, check this skill's references/ directory for framework-specific instructions. Framework bindings share the same route, store, and URL contracts.
Tracking URLs
Use getPredictiveSearchItemUrl() for predictive result links. It infers Hydrogen's standard storefront route from the item's __typename and keeps Storefront API trackingParameters without double-encoding:
import { getPredictiveSearchItemUrl } from "@shopify/hydrogen";
const productHref = getPredictiveSearchItemUrl(product, { routes: routeTemplates, term });
const querySuggestionHref = getPredictiveSearchItemUrl(querySuggestion, {
routes: routeTemplates,
});Pass {term} for resource items such as products, collections, pages, and articles. These items do not contain the shopper's typed search text, but the destination URL needs it for attribution. Do not pass {term} for SearchQuerySuggestion items; the helper uses querySuggestion.text automatically. Pass {routes: routeTemplates} so query suggestions honor a custom search route. Pass {searchPath} only when the suggestion link intentionally differs from the shared search route; it takes precedence when provided.
If the storefront uses custom Shopify resource paths, use the local hydrogen-routing skill before wiring predictive search result URLs. Do not create predictive-search-only URL callbacks.
Use getSearchResultUrl() only when constructing a custom search-attributed URL that is not backed by a predictive search item.
Do not publish a new analytics event for predictive suggestions. Full search pages can keep their existing search-view analytics; predictive result links carry attribution through tracking parameters.
Custom Fragments
Use additive fragments when the UI needs extra result fields:
import {
createPredictiveSearchServerHandlers,
gql,
makePredictiveSearchQueries,
queryPredictiveSearch,
} from "@shopify/hydrogen";
const predictiveSearchFragments = {
product: gql(`
fragment PredictiveSearchProductFragment on Product {
vendor
}
`),
};
const predictiveSearchHandlers = createPredictiveSearchServerHandlers({
fragments: predictiveSearchFragments,
});
const queries = makePredictiveSearchQueries({
fragments: predictiveSearchFragments,
});
const data = await queryPredictiveSearch({
storefrontClient,
term,
query: queries.predictiveSearch,
});Use the route-handler form for browser-backed autocomplete. Use makePredictiveSearchQueries() when querying directly from server code. Keep fragment names as documented by the API types. Hydrogen composes these with required base fields such as IDs, handles, titles, prices, images, and tracking parameters.
Rules
- Use the packaged route handler as the default browser transport.
- Degrade to a normal search without JavaScript. The search entry point must be a real
/searchlink or arole="search"GET form, and the predictive modal's form must submitGET /searchnatively (formProps()defaults to this). Predictive autocomplete is an enhancement layered on top — never the only way to reach search results. With JS off, the trigger navigates to/search(or submits the term to it) and the full search page renders results server-side. - Keep UI rendering and layout app-owned.
- Preserve
trackingParameterson every predictive result link. - Use
qfor the search term so predictive and full search URLs align. - Use the local
hydrogen-routingskill for result URLs when the app uses custom Shopify resource paths. - Render store errors near the search UI.
- Keep debounce in the client store; do not add ad-hoc debounce in components unless there is a separate UX reason.
- Prefer additive fragments over full query overrides.
- Return empty UI for blank terms rather than querying Storefront API.
- The modal is a native
<dialog>opened withshowModal(). For backdrop-dismiss, useclosedby="any"where supported. For browsers withoutclosedbysupport, use a pointerdown-plus-click guard: record whetherpointerdownstarted on the dialog backdrop, then close only when the followingclickalso targets the dialog. Do not close on a plainclick.selfalone — a drag that starts inside and ends on the backdrop can produce an accidental close.
Verify
Done when:
- Search works without JavaScript: a real
/searchlink orrole="search"GET form reaches server-rendered results, and the predictive modal's form submitsGET /searchnatively. - Browser autocomplete goes through the same-origin
/api/predictive-searchroute. - Every predictive result link preserves
trackingParameters(built withgetPredictiveSearchItemUrl()). - Blank terms render empty UI without querying the Storefront API.
- Store errors surface near the search UI.
- The search term uses
qso predictive and full search URLs align.
Anti-patterns
- Gating search behind JavaScript — a search trigger that only opens a JS autocomplete overlay, with no
/searchlink or native GET form underneath, leaves no-JS shoppers with no way to search. The predictive layer must enhance a working/searchpath, not replace it. - Calling Storefront API directly from browser UI when a same-origin route can proxy the request.
- Reusing
/search?predictive=trueas the autocomplete API when/api/predictive-searchis available. - Dropping or manually concatenating tracking parameters.
- Hard-coding predictive result links separately from the app's routing primitive.
- Duplicating predictive search state in framework component state when the Hydrogen store already owns request lifecycle, debounce, aborts, and stale response handling.
- Shipping a visual autocomplete component as the primary abstraction.
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.

