The provideHeadless function provides a newly created SearchHeadless instance that can be used in any nested components when added to a SearchHeadlessProvider.

Basic Example

provideHeadless is used in conjunction with the SearchHeadlessProvider. The apiKey, experienceKey, and locale fields are required to create a new SearchHeadless instance.

The apiKey and experienceKey can be found in the platform by navigating to Search > [Your Search Experience] > General Settings.

Here is an example of a component used to wrap templates in Yext Pages:

import {
  provideHeadless,
  SearchHeadlessProvider
} from "@yext/search-headless-react";

const searcher = provideHeadless({
  apiKey: YEXT_PUBLIC_SEARCH_API_KEY,
  experienceKey: "ecomm-search",
  locale: "en",
});

const Main = ({ children }: { children: React.ReactNode }) => {
  return (
    <SearchHeadlessProvider searcher={searcher}>
      {children}
    </SearchHeadlessProvider>
  );
};

Initial Search Mode

By default, SearchHeadless will be in Universal search mode, meaning all searches triggered from the SearchBar component will be universal queries. To change the default SearchBar behavior, provide a verticalKey to provideHeadless:

import { provideHeadless } from "@yext/search-headless-react";

const searcher = provideHeadless({
  apiKey: YEXT_PUBLIC_SEARCH_API_KEY,
  experienceKey: "ecomm-search",
  locale: "en",
  verticalKey: "products"
});

Using Sandbox Accounts

If you're using a Yext sandbox account, import Environment from @yext/search-headless-react and pass the Sandbox environment to the environment prop:

import {
  provideHeadless,
  Environment,
  SandboxEndpoints
} from "@yext/search-headless-react";

const searcher = provideHeadless({
  apiKey: YEXT_PUBLIC_SEARCH_API_KEY,
  experienceKey: "ecomm-search",
  locale: "en",
  environment: Environment.SANDBOX
});

Adding Additional Search Headless Instances

You may want to add additional SearchHeadless instances to a site — for example, when you want both a product and support search bar on the same page, or when implementing visual autocomplete.

When creating additional instances, include a unique headlessId when calling provideHeadless:

import * as React from "react";
import { provideHeadless } from "@yext/search-headless-react";

const entityPreviewSearcher = provideHeadless({
  apiKey: YEXT_PUBLIC_SEARCH_API_KEY,
  experienceKey: "ecomm-search",
  locale: "en",
  headlessId: "entity-preview-searcher"
});

Note: The first SearchHeadless instance you add to your site will have an ID of main, which is why you only need to add headlessId when making additional calls to provideHeadless.

Component API

Check out the component properties on GitHub.