Get Started with Search UI React – Yext Help

Search UI React is a React component library designed to make developing custom, headless search experiences easy. It contains fully-styled React components and a series of hooks that allow you to create your own search components by pulling data from a managed Search state and creating new requests with Search actions.

The library is available on GitHub.

Components

Search UI React includes fully-styled components such as:

For the full list of available components and their APIs, see the Search UI React GitHub repo.

This doc will walk you through setting up a Yext Pages project with Search UI React, configuring it for Search, and adding your first components.

Prerequisites: Check out the list of development dependencies for what you need before getting started. You will also need the latest version of the Yext CLI installed and a blank playground account.

Step 1: Create Your Project

Search UI React is compatible with Yext Pages, Vite, Create React App, Next.js, and more. This guide is built on Yext Pages.

yext init -u sandbox [YOUR_PLAYGROUND_ACCOUNT_ID]

Then run:

yext pages new

You will be walked through a series of prompts. Respond as follows:

Would you like to create a new repo or link an existing GitHub repo? Create a new repo
Which starter repository would you like to use? Search UI React Track Starter
What would you like to call your new Pages repo? tt-job-search
Would you like to set up a remote GitHub repository for tt-job-search? Y — this sets up a remote repo and makes deploying easy. If not logged into GitHub, follow the browser prompts and return to the command line when finished.
Would you like to install dependencies for tt-job-search? Y — this runs npm i and installs all required dependencies.
Would you like to populate your account with seed data? Y — recommended for a fresh account. Be careful when adding seed data to an account with existing data.
Warning: Are you sure you want to overwrite configuration resources for the current configuration? Yes — confirm you are connected to the correct account.

Step 2: Install the Library

Navigate to your new project:

cd tt-job-searcher

Install Search UI React:

npm install @yext/search-ui-react @yext/search-headless-react

Step 3: Configure Tailwind CSS

Search UI React components work best with Tailwind CSS. Tailwind is already installed in the starter project, but you need to add the path to where Search UI React lives within node_modules to tailwind.config.js so that Tailwind CSS is applied to the Search UI components.

Replace the contents of tailwind.config.cjs with the following:

// tailwind.config.cjs

const { ComponentsContentPath } = require("@yext/search-ui-react");

module.exports = {
  content: [
    "./src/**/*.{ts,tsx}",
    "./lib/**/*.{js,jsx}",
    ComponentsContentPath,
  ],
  theme: {
    extend: {
      colors: {
        primary: "var(--primary-color, #2563eb)",
        "primary-light": "var(--primary-color-light, #dbeafe)",
        "primary-dark": "var(--primary-color-dark, #1e40af)",
        neutral: "var(--neutral-color, #4b5563)",
        "neutral-light": "var(--neutral-color-light, #9ca3af)",
        "neutral-dark": "var(--neutral-color-dark, #1f2937)",
      },
      borderRadius: {
        cta: "var(--cta-border-radius, 1rem)",
      },
      keyframes: {
        rotate: {
          "100%": { transform: "rotate(360deg)" },
        },
        dash: {
          "0%": { transform: "rotate(0deg)", "stroke-dashoffset": 204 },
          "50%": { transform: "rotate(45deg)", "stroke-dashoffset": 52 },
          "100%": { transform: "rotate(360deg)", "stroke-dashoffset": 204 },
        },
      },
    },
  },
  plugins: [
    require("@tailwindcss/forms")({
      strategy: "class",
    }),
  ],
};

Step 4: Configure Your Application for Search

Under the hood, Search UI React uses the Yext Search API to make search query requests and display results. You need to add your Search experience credentials to your front-end configuration.

Get Your Configuration Information

Navigate to the General Settings screen within your sandbox account to find your Search API Key and Experience Key.

Configure Your Application

Add the following code to src/templates/search.tsx:

Note: Replace the apiKey value with your Search API Key.

// src/templates/search.tsx

import {
  Template,
  GetPath,
  TemplateRenderProps,
  GetHeadConfig,
  HeadConfig,
  TemplateProps,
} from "@yext/pages";
import "../index.css";
import {
  SearchHeadlessProvider,
  provideHeadless,
  HeadlessConfig,
  Environment,
} from "@yext/search-headless-react";

export const getPath: GetPath<TemplateProps> = () => {
  return "search";
};

export const getHeadConfig: GetHeadConfig<
  TemplateRenderProps
> = (): HeadConfig => {
  return {
    title: `Turtlehead Tacos Search`,
    charset: "UTF-8",
    viewport: "width=device-width, initial-scale=1",
  };
};

const headlessConfig: HeadlessConfig = {
  apiKey: "Your_Search_API_Key",
  experienceKey: "turtlehead",
  locale: "en",
  verticalKey: "faqs",
  environment: Environment.SANDBOX,
};

const searcher = provideHeadless(headlessConfig);

const Search: Template<TemplateRenderProps> = () => {
  return <SearchHeadlessProvider searcher={searcher}></SearchHeadlessProvider>;
};

export default Search;

Here's what the code above does:

The headlessConfig object contains the required fields (apiKey, experienceKey, locale) for configuring a search experience. The optional verticalKey is set to "faqs", meaning any search from the SearchBar will trigger a Vertical Query on the FAQs vertical. The sandbox environment overrides the default search endpoints for use with a Sandbox account.
provideHeadless instantiates the searcher object, which is a SearchHeadless instance.
The searcher is passed to the SearchHeadlessProvider. Any component wrapped by the provider will have access to the SearchHeadless hooks.

Note: You only need to add the Sandbox environment to the HeadlessConfig if you are using a Sandbox account.

Step 5: Add Components

In src/templates/search.tsx, add the following imports from @yext/search-ui-react:

import {
  SearchBar,
  StandardCard,
  VerticalResults,
  SpellCheck,
  ResultsCount,
  Pagination,
} from "@yext/search-ui-react";

Then wrap the components inside the SearchHeadlessProvider:

const Search: Template<TemplateRenderProps> = () => {
  return (
    <SearchHeadlessProvider searcher={searcher}>
      <div className="px-4 py-8">
        <div className="mx-auto flex max-w-5xl flex-col">
          <SearchBar />
          <SpellCheck />
          <ResultsCount />
          <VerticalResults
            CardComponent={StandardCard}
            displayAllOnNoResults={false}
          />
        </div>
        <Pagination />
      </div>
    </SearchHeadlessProvider>
  );
};

Here's what each component does:

SearchBar — includes autocomplete out of the box. When typing a query like "what…" or "who", you will see query suggestions. After your first search, the autocomplete dropdown will show recent searches when focused.
SpellCheck — displays a "Did you mean [corrected spelling]" prompt with a link to execute a new search. Try searching "jobz" to see this in action.
VerticalResults — renders search results in a list using the component passed as the CardComponent prop.
ResultsCount — displays the number of results shown on the page.
StandardCard — displays the name, description, and c_primaryCta for any result that has data for those fields on the corresponding entity. Note: for the built-in FAQ entity type, the Question field is returned as name by the API.
Pagination — allows the user to click through pages of results.

Step 6: Add Analytics

Follow the Get Started with Analytics guide to add analytics to your search experience.

Step 7: Run Your Application

Run your application locally:

npm run dev

Click on the search page and try running a few queries like "jobs" and "delivery".

To confirm what your code should look like at this point, see the module-1 branch in the pages-starter-search-ui-react repo.