Search result URLs
The search result URL functions build links for predictive search results and search pages. Use these functions to link each result to its page and keep the result's tracking parameters in the link.
Import getPredictiveSearchItemUrl and getSearchResultUrl from @shopify/hydrogen.
Anchor to Predictive result linksPredictive result links
Builds the link for a predictive search result. A product, collection, page, or article result links to the resource's page with the search term. A query suggestion links to the search page and searches for the suggestion's text. Every link keeps the result's tracking parameters.
For a product, collection, page, or article, pass the route templates and the search term. The function throws an error without them.
- Anchor to itemitemitemPredictiveSearchItemPredictiveSearchItemrequiredrequired
The predictive search result to link to.
- Anchor to optionsoptionsoptionsAnyPredictiveSearchItemUrlOptionsAnyPredictiveSearchItemUrlOptions
Route templates, search term, and path settings for the link.
Anchor to getPredictiveSearchItemUrl-returnsReturnsstringstring
The link URL. The URL is relative unless you pass an absolute search path.
PredictiveSearchItem
Any predictive search result, including query suggestions.
PredictiveSearchResourceItem | PredictiveSearchQueryItemPredictiveSearchResourceItem
A product, collection, page, or article result. Excludes query suggestions.
PredictiveSearchProductItem | PredictiveSearchCollectionItem | PredictiveSearchPageItem | PredictiveSearchArticleItemPredictiveSearchProductItem
PredictiveSearchCollectionItem
A collection result from predictive search.
{ __typename: 'Collection'; id: string; title: string; handle: string; image: { url: string; altText: string; width: number; height: number; }; trackingParameters: string; }PredictiveSearchPageItem
A page result from predictive search.
{ __typename: 'Page'; id: string; title: string; handle: string; trackingParameters: string; }PredictiveSearchArticleItem
An article result from predictive search.
{ __typename: 'Article'; id: string; title: string; handle: string; blog: { handle: string; }; image: { url: string; altText: string; width: number; height: number; }; trackingParameters: string; }PredictiveSearchQueryItem
A suggested search term from predictive search.
{ __typename: 'SearchQuerySuggestion'; text: string; styledText: string; trackingParameters: string; }AnyPredictiveSearchItemUrlOptions
URL options for any predictive search result, either resource options or query suggestion options.
PredictiveSearchItemUrlOptions | PredictiveSearchQueryItemUrlOptionsPredictiveSearchItemUrlOptions
Options for the link of a product, collection, page, or article result. Pass the route templates and the customer's search term.
- pathPrefix
Prefix to add before the route path, such as a locale prefix.
string - routes
Route templates for product, collection, page, and article paths, from `createShopifyRouteTemplates`.
ShopifyRouteTemplates - term
Search term that the customer typed. The link carries the term in the `q` URL parameter.
string
ShopifyRouteTemplates
Your app's custom path templates for Shopify standard storefront routes, keyed by route name.
- article
The app's article path. Hydrogen redirects Shopify article paths, such as `/blogs/news/snowboard-guide`, to this template.
StandardRouteTemplateWithParam<"blogHandle"> & StandardRouteTemplateWithParam<"articleHandle"> - blog
The app's blog path. Hydrogen redirects Shopify blog paths, such as `/blogs/news`, to this template.
StandardRouteTemplateWithParam<"blogHandle"> - cart
The app's cart path. Hydrogen redirects Shopify's `/cart` path to this template.
StandardRouteTemplate - collection
The app's collection path. Hydrogen redirects Shopify collection paths, such as `/collections/winter`, to this template.
StandardRouteTemplateWithParam<"collectionHandle"> - collectionList
The app's collection list path. Hydrogen redirects Shopify's `/collections` path and the legacy `/products` path to this template.
StandardRouteTemplate - page
The app's page path. Hydrogen redirects Shopify page paths, such as `/pages/about-us`, to this template.
StandardRouteTemplateWithParam<"pageHandle"> - policy
The app's policy path. Hydrogen redirects Shopify policy paths, such as `/policies/privacy-policy`, to this template.
StandardRouteTemplateWithParam<"policyHandle"> - product
The app's product path. Hydrogen redirects Shopify product paths, such as `/products/snowboard`, to this template.
StandardRouteTemplateWithParam<"productHandle"> - productInCollection
The app's path for products inside a collection. Hydrogen redirects Shopify paths such as `/collections/winter/products/snowboard` to this template. The template must include `:productHandle`. Add `:collectionHandle` when the app's product path also names the collection.
StandardRouteTemplateWithParam<"productHandle"> - search
The app's search path. Hydrogen redirects Shopify's `/search` path to this template.
StandardRouteTemplate
StandardRouteTemplateWithParam
A path template that starts with `/` and includes the named handle placeholder.
`/${string}:${Param}` | `/${string}:${Param}/${string}`StandardRouteTemplate
A path template that starts with `/`.
`/${string}`PredictiveSearchQueryItemUrlOptions
Options for the link of a query suggestion. By default, a suggestion links to the standard search route and searches for the suggestion's text.
- pathPrefix
Prefix to add before the search route, such as a locale prefix. Has no effect when you set a search path.
string - routes
Route templates that set the search page path. Defaults to Hydrogen's standard search route.
ShopifyRouteTemplates - searchPath
Search page path or URL to use as is, without the route templates or the path prefix.
string
TypeScript
Examples
Description
Link product results with the customer's search term, and link query suggestions to the search page. This example builds links from shared route templates.
TypeScript
import { createShopifyRouteTemplates, getPredictiveSearchItemUrl, type PredictiveSearchData, } from "@shopify/hydrogen"; const routeTemplates = createShopifyRouteTemplates({}); export function getResultLinks({ term, items }: PredictiveSearchData) { return { products: items.products.map((product) => getPredictiveSearchItemUrl(product, { routes: routeTemplates, term }), ), queries: items.queries.map((query) => getPredictiveSearchItemUrl(query, { routes: routeTemplates }), ), }; }Description
Render each product result as a tracked link. This example reads the result from `usePredictiveSearch` in `@shopify/hydrogen/react` and passes the result's `term` to `getPredictiveSearchItemUrl`.
React
import { createShopifyRouteTemplates, getPredictiveSearchItemUrl } from "@shopify/hydrogen"; import { usePredictiveSearch } from "@shopify/hydrogen/react"; const routeTemplates = createShopifyRouteTemplates({}); export function PredictiveProductLinks() { const { result } = usePredictiveSearch(); return ( <ul> {result.items.products.map((product) => ( <li key={product.id}> <a href={getPredictiveSearchItemUrl(product, { routes: routeTemplates, term: result.term })}> {product.title} </a> </li> ))} </ul> ); }Description
Render each query suggestion as a link to the search page. This example reads the result from `usePredictiveSearch` in `@shopify/hydrogen/vue` and passes route templates to `getPredictiveSearchItemUrl`.
Vue
<script setup lang="ts"> import { createShopifyRouteTemplates, getPredictiveSearchItemUrl } from "@shopify/hydrogen"; import { usePredictiveSearch } from "@shopify/hydrogen/vue"; const routeTemplates = createShopifyRouteTemplates({}); const state = usePredictiveSearch(); </script> <template> <ul> <li v-for="query in state.result.items.queries" :key="query.text"> <a :href="getPredictiveSearchItemUrl(query, { routes: routeTemplates })">{{ query.text }}</a> </li> </ul> </template>
Anchor to Search page linksSearch page links
Builds a search page URL from a path, a search term, and optional extra parameters. Use the function for search page links, such as a link to every result for the current term.
The search term and the extra parameters replace values with the same names in the base URL.
Anchor to getSearchResultUrl-parametersParameters
- Anchor to input1input1input1SearchResultUrlOptionsSearchResultUrlOptionsrequiredrequired
The base URL, the search term, the extra and tracking parameters, and the search parameter name.
Anchor to getSearchResultUrl-returnsReturnsstringstring
A relative URL, or an absolute URL when the base URL is absolute.
SearchResultUrlOptions
Options for a search result URL.
- baseUrl
Search page path or absolute URL.
string - params
Extra URL parameters, such as a result type filter. The search term replaces an extra parameter with the same name.
Record<string, string> - searchParamName
URL parameter that carries the search term. Defaults to `q`.
string - term
Search term to add to the URL.
string - trackingParameters
Tracking parameters from a Storefront API search result. Pass the result's `trackingParameters` value unchanged.
string | null
TypeScript
Examples
Description
Build `/search?type=product&q=snow+board` from a base path, a term, and an extra `type` parameter.
TypeScript
import { getSearchResultUrl } from "@shopify/hydrogen"; const url = getSearchResultUrl({ baseUrl: "/search", term: "snow board", params: { type: "product" }, }); console.log(url);