Skip to main content

Predictive search server handlers

The predictive search server functions get predictive search results from the Storefront API. Use these functions to serve the route that your search UI calls, run predictive search in a loader, and add fields to each result type.

Import createPredictiveSearchServerHandlers, queryPredictiveSearch, and makePredictiveSearchQueries from @shopify/hydrogen.

Anchor to Search routeSearch route

Anchor to createPredictiveSearchServerHandlers
createPredictiveSearchServerHandlers(
options
)

Creates the route that answers predictive search requests from the browser. Register the handlers with handleShopifyRoutes. The default route path matches the default endpoint of createPredictiveSearchStore and PredictiveSearchProvider.

The route reads the search term from the q URL parameter. A URL parameter with the same name as a search setting overrides the setting's default.

An invalid setting value or a failed Storefront API query returns HTTP status 400 with a JSON body of {error: {code, message}}. The code value is invalid_predictive_search_request. A successful response forwards the Storefront API response headers except the content encoding, content length, and server timing headers.

Anchor to createPredictiveSearchServerHandlers-parametersParameters

Anchor to options
options
Default: {}

Route path, custom fragments, and default search settings for the route.

Anchor to createPredictiveSearchServerHandlers-returnsReturns

<>

Route handlers to pass to handleShopifyRoutes.

Examples

TypeScript

import { createPredictiveSearchServerHandlers, handleShopifyRoutes } from "@shopify/hydrogen";

type ShopifyRoutesOptions = Parameters<typeof handleShopifyRoutes>[0];

const predictiveSearchHandlers = createPredictiveSearchServerHandlers({
types: ["PRODUCT"],
});

export function handleRoutes(options: Omit<ShopifyRoutesOptions, "handlers">) {
return handleShopifyRoutes({
...options,
handlers: [predictiveSearchHandlers],
});
}

Anchor to Server-side queriesServer-side queries

Anchor to queryPredictiveSearch
queryPredictiveSearch(
options
)

Queries the Storefront API for predictive search results. Use the function in server code, such as a route loader. Pass the Storefront client and the search term.

The function throws an error when the Storefront API returns GraphQL errors or no predictive search data. Network failures and aborts from the Storefront client also throw.

To serve results to the browser with the Storefront API response headers, use createPredictiveSearchServerHandlers.

Anchor to queryPredictiveSearch-parametersParameters

Anchor to options
options
<<undefined>>
required

The Storefront client, the search term, a custom query, and search settings.

Anchor to queryPredictiveSearch-returnsReturns

Promise<>

The search term, the result count, and the results grouped by type.

Examples

TypeScript

import { queryPredictiveSearch, type QueryPredictiveSearchOptions } from "@shopify/hydrogen";

export async function searchProducts(
storefrontClient: QueryPredictiveSearchOptions["storefrontClient"],
term: string,
) {
const { total, items } = await queryPredictiveSearch({
storefrontClient,
term,
limit: 5,
types: ["PRODUCT"],
});

return { total, products: items.products };
}

Anchor to Custom result fieldsCustom result fields

Anchor to makePredictiveSearchQueries
makePredictiveSearchQueries(
options
)

Builds a predictive search query that adds the fields from your fragments to the results.

Pass the query to queryPredictiveSearch, or pass the same fragments to createPredictiveSearchServerHandlers. TypeScript types the results from your fragments. The function throws an error when a fragment doesn't use its required name and type.

Anchor to makePredictiveSearchQueries-parametersParameters

Anchor to options
options
<>

Fragments that add fields to each result type.

Examples

TypeScript

import {
gql,
makePredictiveSearchQueries,
queryPredictiveSearch,
type QueryPredictiveSearchOptions,
} from "@shopify/hydrogen";

const queries = makePredictiveSearchQueries({
fragments: {
product: gql(`
fragment PredictiveSearchProductFragment on Product {
vendor
}
`),
},
});

export async function searchWithVendor(
storefrontClient: QueryPredictiveSearchOptions["storefrontClient"],
term: string,
) {
const data = await queryPredictiveSearch({
storefrontClient,
term,
query: queries.predictiveSearch,
});

return data.items.products.map((product) => product.vendor);
}
Was this page helpful?