Build search interfaces (Shopify Hydrogen)

This is for:

Developer

In this article

Prerequisites
Creating a search box
Displaying the search page with the search provider

Building a search interface with Coveo Headless and Shopify Hydrogen involves three main components: a search box, a search page, and a search provider.

The Coveo Headless React package provides two types of search box controllers: the SearchBox and the StandaloneSearchBox. It also exposes functions to create a search provider, which you can use to manage the search page and results.

Complete examples are available in the Barca Sports Hydrogen repository.

Prerequisites

Before you begin building your search interface, make sure you:

To create a search box, use the SearchBox and StandaloneSearchBox controllers:

SearchBox: Use this controller to create a search box component in your search interface, submit queries, and display query suggestions. This controller is used on the search page itself.
StandaloneSearchBox: Use this controller to create a standalone search box that redirects to your search page. This controller is used on every page of your app except the search page.

Define the controllers

Create a component that uses the SearchBox controller for the search page and a lightweight standalone search box component that uses the StandaloneSearchBox controller to redirect to your search page. This standalone search box component should be included on every page of your app except the search page.

When defining your commerce engine, define both search box controllers.

// lib/commerce-engine-config.ts

import {
  defineSearchBox,
  defineStandaloneSearchBox,
  // ...
} from '@coveo/headless-react/ssr-commerce';

export default {
  // ...
  controllers: {
    searchBox: defineSearchBox(), 
    standaloneSearchBox: defineStandaloneSearchBox({ 
      options: {redirectionUrl: '/search'},
    }),
    // ...
  },
} satisfies CommerceEngineDefinitionOptions;

	Define the `SearchBox` controller via the `defineSearchBox` function.
	Define the `StandaloneSearchBox` controller via the `defineStandaloneSearchBox` function and specify the redirection URL. When the user submits a query in this search box, the `state.redirectTo` is updated to `/search`. This update can be detected by subscribing to the controller state and then used to redirect the user to the search page.

Using the controllers

The following example shows how to create a component using the StandaloneSearchBox controller.

The SearchBox component isn’t included in this article, but it follows a similar implementation without the redirection logic.

import {useEffect, useRef} from 'react';
import {useStandaloneSearchBox} from '~/lib/commerce-engine.ts';
import {useNavigate} from '@remix-run/react';

export function StandaloneSearchBox() {
  const searchBox = useStandaloneSearchBox(); 
  const inputRef = useRef<HTMLInputElement>(null);
  const navigate = useNavigate();

  useEffect(() => { 
    inputRef.current?.focus();
  }, []);

  useEffect(() => { 
    if (searchBox.state.redirectTo === '/search') {
      navigate(
        `${searchBox.state.redirectTo}?q=${encodeURIComponent(
          searchBox.state.value,
        )}`,
      );
    }
  }, [searchBox.state.redirectTo, searchBox.state.value]);

  const handleSuggestionClick = (suggestion: string) => {
    searchBox.methods?.updateText(suggestion);
    inputRef.current!.value = suggestion;
    searchBox.methods?.showSuggestions();
  };

  return (
    <div>
      <input 
        ref={inputRef}
        aria-label="Search"
        placeholder="Search"
        onChange={(e) => searchBox.methods?.updateText(e.target.value)}
        onFocus={() => searchBox.methods?.showSuggestions()}
      />
      <button onClick={searchBox.methods?.submit}>Search</button>

      {searchBox.state.suggestions.length > 0 && ( 
        <div>
          {searchBox.state.suggestions.map((suggestion) => (
            <button
              key={suggestion.rawValue}
              onClick={() => handleSuggestionClick(suggestion.rawValue)} 
              dangerouslySetInnerHTML={{__html: suggestion.highlightedValue}}
            />
          ))}
        </div>
      )}
    </div>
  );
}

	Use the `useStandaloneSearchBox` hook to access the `StandaloneSearchBox` controller.
	Focus the input field when the component mounts.
	Redirect the user to the search page when the `redirectTo` state is updated to `/search`. Navigate to the search page with the query text.
	Render the input field and bind the necessary event handlers. As the user types, update the query text and show suggestions using the `updateText` and `showSuggestions` methods.
	Loop through the suggestions and render them.
	Handle the suggestion click event. Update the search box text, show the suggestions, and set the input value.

Displaying the search page with the search provider

Once the search box is set up, you must display the search results on the search page, using your search provider, which manages facets, sorting, and pagination to ensure a seamless user experience.

For your search page route, add the following code to render the search page with the search provider.

import {type LoaderFunctionArgs} from '@shopify/remix-oxygen';
import {useLoaderData, type MetaFunction} from '@remix-run/react';
import {
  fetchStaticState,
  searchEngineDefinition,
  type SearchStaticState,
} from '~/lib/commerce-engine.ts';
import {
  ClientSideNavigatorContextProvider,
  ServerSideNavigatorContextProvider,
} from '~/lib/navigator.provider';
import {SearchProvider} from '~/components/Search/Context';
import ParameterManager from '~/components/ParameterManager';
import {buildParameterSerializer} from '@coveo/headless-react/ssr-commerce';
import {useEffect, useState} from 'react';
import {Facets} from '~/components/Search/Facets';
import {Sorts} from '~/components/Search/Sorts';
import {Pagination} from '~/components/Search/Pagination';
import {ProductList} from '~/components/Search/ProductList';

export const meta: MetaFunction = () => {
  return [{title: `Coveo | Search`}];
};

export type SearchLoader = typeof loader;

export async function loader({request, context}: LoaderFunctionArgs) { 
  const url = new URL(request.url);
  const {deserialize} = buildParameterSerializer();
  const parameters = deserialize(url.searchParams); 
  const q = url.searchParams.get('q') || '';

  searchEngineDefinition.setNavigatorContextProvider( 
    () => new ServerSideNavigatorContextProvider(request),
  );

  const staticState = await fetchStaticState({ 
    context,
    k: 'searchEngineDefinition',
    parameters,
    url: `https://shop.barca.group`,
    request,
  });

  return {staticState, q, url};
}

export default function SearchPage() {
  const {staticState, q, url} = useLoaderData<typeof loader>();
  const [currentUrl, setCurrentUrl] = useState(url);

  useEffect(() => {
    setCurrentUrl(window.location.href);
  }, []);

  return (
    <SearchProvider 
      navigatorContext={new ClientSideNavigatorContextProvider()}
      staticState={staticState as SearchStaticState}
    >
      <ParameterManager url={currentUrl} /> 
      <SearchBox /> 
      <ProductList /> 
      <Facets /> 
      <Sorts />
      <Pagination />
    </SearchProvider>
  );
}

	Use the `loader` function to run server-side code.
	Fetch the deserialized search parameters from the URL.
	Set the navigator context provider to the server-side context provider.
	Fetch the static state for the search page.
	Wrap the search page with the `SearchProvider` component.
	Use the `ParameterManager` component to manage search parameters.
	Render a `SearchBox` component to display the search box. This component will be similar to the standalone search box component, but it will use the `SearchBox` controller instead of the `StandaloneSearchBox` controller and not include the redirection logic.
	Render the `ProductList` component to display search results.
	Render the `Facets` component to display facets. Similarly, render the `Sorts` and `Pagination` components to display sorting and pagination controls. For more details, see Leveraging facets, sorting, and pagination.

A complete example of how to build a search page is available in the Barca Sports Hydrogen repository.

Within the sample project, you can find additional components that were omitted in this article, such as the BreadcrumbManager which displays a summary of the currently active facet values.

Was this article useful?

Very useful

Not really