Building a custom coveo headless search experience in sitecore JSS (Next.js)

As businesses aim to deliver high-performance, scalable, and personalized digital experiences, combining Sitecore XM Cloud with Coveo Headless offers a modern, composable search architecture. In this blog, we will walk through building a custom search interface using Coveo Headless inside a Sitecore JSS (Next.js) application.

In our previous blog, we explored how Coveo Atomic works with Sitecore JSS and why many teams are now shifting toward Headless for more flexibility. In this blog, we will take the next step by showing how to create your own custom search experience using Coveo Headless with a Sitecore JSS (Next.js) project.

Whether you are a developer or a digital strategist, you will understand how to connect Sitecore-managed content with Coveo-powered search, all from the frontend development side.

Why use Coveo Headless with Sitecore?

From a business perspective:

• Speed and relevance drive conversions. Coveo’s AI-based ranking ensures users find what they need.
• Personalization means users see what matters to them, improving engagement and reducing bounce.
• Scalability and control: Sitecore and Coveo together support multisite, multilingual, and multi-region setups with tailored experiences.

From a developer’s perspective:

• You get full control of UI and logic. No design restrictions from prebuilt components.
• Component-based, modern, and API-first architecture using React and TypeScript.
• Seamlessly fetch and display Sitecore-managed content using GraphQL or Layout Service alongside Coveo results.

Before explore more, make sure:

• You have a Sitecore XM Cloud project using JSS with Next.js set up.
• You have created a Coveo Organization and a Search Token via the Coveo Cloud Admin UI.
• You have indexed some Sitecore content into Coveo using the Coveo connector or push API.

Step 1: Install Coveo Headless

Install the required Headless engine and dependencies:

This gives you access to Coveo’s frontend engine that handles state management, search logic, and interactions.

npm install @coveo/headless

Step 2: Initialize the Coveo Engine

Create a file: src/lib/coveo/coveoEngine.ts

// src/lib/coveo/coveoEngine.ts
import {
  buildSearchEngine,
  loadFieldActions,
  SearchEngine,
} from "@coveo/headless";

const FIELDS = ["...your Fields"];
const accessToken = process.env.NEXT_PUBLIC_COVEO_API_KEY;
const organizationId = process.env.NEXT_PUBLIC_COVEO_ORG_ID;

const registerAdditionalFields = (headlessEngine: SearchEngine) => {
  const fieldActions = loadFieldActions(headlessEngine);
  headlessEngine.dispatch(fieldActions.registerFieldsToInclude(FIELDS));
  return headlessEngine;
};

export const buildEngine = buildSearchEngine({
  configuration: {
    organizationId: organizationId,
    accessToken: accessToken,
    search: {
      searchHub: searchHub,
      pipeline: queryPipeline,
    },
  },
});

export const headlessEngine = registerAdditionalFields(buildEngine);

Step 3: Set up a search box controller

Let’s add a basic search box component.

// src/components/SearchBox.tsx
'use client';
import { useEffect, useState } from 'react';
import { buildSearchBox, SearchBox as SearchBoxController } from '@coveo/headless';
import { searchEngine } from '../lib/coveo/coveoEngine';

export default function SearchBox() {
  const [controller, setController] = useState<SearchBoxController>();
  const [value, setValue] = useState('');

  useEffect(() => {
    const newController = buildSearchBox(searchEngine, {
      options: { numberOfSuggestions: 5 },
    });
    setController(newController);
    newController.subscribe(() => setValue(newController.state.value));
  }, []);

  const submitSearch = () => controller?.submit();

  return (
    <div>
      <input
        value={value}
        onChange={(e) => controller?.updateText(e.target.value)}
        onKeyDown={(e) => e.key === 'Enter' && submitSearch()}
        placeholder="Search..."
      />
      <button onClick={submitSearch}>Search</button>
    </div>
  );
}

Step 4: Show the results

Render results using buildResultList.

// components/SearchResults.tsx
'use client';
import { useEffect, useState } from 'react';
import { buildResultList, ResultList } from '@coveo/headless';
import { searchEngine } from '../lib/coveo/coveoEngine';

export default function SearchResults() {
  const [controller, setController] = useState<ResultList>();
  const [results, setResults] = useState([]);

  useEffect(() => {
    const resultList = buildResultList(searchEngine, { options: { fieldsToInclude: ['title', 'excerpt'] } });
    setController(resultList);
    resultList.subscribe(() => setResults(resultList?.state?.results));
  }, []);

  return (
    <div>
      {results.map((result: any) => (
        <div key={result.uniqueId}>
          <h3>{result.raw.title}</h3>
          <p>{result.raw.excerpt}</p>
        </div>
      ))}
    </div>
  );
}

If you want to display more fields from Sitecore, just add them to the fieldsToInclude array and use result.raw.your_field_name.

Sitecore Integration:

You may want to show search results that reflect Sitecore content types (e.g., Articles, Products).

There are two ways to connect this:

1. Indexing Strategy: Ensure Sitecore templates include meaningful field mappings (title, image, tags).
2. Dynamic Layout: Use Sitecore Layout Service to load page context (site name, language, personalization rules) and show content accordingly.

This makes the frontend easy to build while still showing the right content.

You can further add more functionalities to the search interface:

• Add sorting using buildSort.
• Include filters using buildFacet/buildCategoryFacet
• Include pagination using buildPager

Developer Experience:

• you have full control as no tight coupling with any UI library.
• Everything is typed with TypeScript.
• It works seamlessly with Sitecore’s disconnected/connected modes.
• Easily scaled and customized per environment.

Conclusion:

Coveo Headless and Sitecore JSS are a good match. Sitecore provides structure, personalization, and full control on site content. Coveo brings relevance, analytics, and powerful search APIs. Together, they help brands deliver best digital experiences.