This document will show you how to quickly add the Search UI React components to a single-page React application.

Prerequisites

Before getting started with this document make sure you have completed the following pre-requisites:

• Code Editor (we recommend VS Code)
• npm or yarn
• Yext Account (If you do not have a Yext account, you can sign up for an account here)
• Yext CLI

1. Create a Blank Pages Project with the Yext CLI

You can use the Yext CLI to scaffold a new Pages project for your account. Run yext pages new and select the Search Starter. Be sure to install dependencies when prompted.

If you already have a Pages project, you can skip this step and follow the next steps.

2. Install Search UI React and Search Headless React

Note: The component library is compatible with React version 16.14 through version 17.0.2.

Install the Library with a Package Manager (Recommended)

If you are using NPM 7+, you can install the components with the following command:

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

3. Configure Tailwind

Configure Content Paths

Update tailwind.config.js to apply styling to the components.

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",
    }),
  ],
};

Styling Without Tailwind

Don’t want to use Tailwind CSS in your project? Not a problem, check out how to do that in the Styling Without Tailwind reference doc.

4. Add the Search Headless Provider and some Components

Next, we’ll import and use the library. Copy and paste the following code into search.tsx (remember to replace the apiKey and experienceKey with values from your Search experience):

// search.tsx

import * as React from "react";
import {
  Template,
  GetPath,
  TemplateRenderProps,
  GetHeadConfig,
  HeadConfig,
  TemplateProps,
} from "@yext/pages";
import "../index.css";
import {
  SearchHeadlessProvider,
  provideHeadless,
  HeadlessConfig,
} from "@yext/search-headless-react";
import {
  SearchBar,
  StandardCard,
  VerticalResults,
} from "@yext/search-ui-react";

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

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

const config: HeadlessConfig = {
  apiKey: "YOUR API KEY",
  experienceKey: "YOUR EXPERIENCE KEY",
  locale: "en",
  verticalKey: "YOUR VERTICAL KEY"
};

const searcher = provideHeadless(config);

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 />
          <VerticalResults
            CardComponent={StandardCard}
            displayAllOnNoResults={false}
          />
        </div>
      </div>
    </SearchHeadlessProvider>
  );
};

export default Search;

Note: In this document, we will be using vertical search. You can select any vertical key from your search configuration and provide it as the verticalKey prop.

A few things to note:

• The Search UI React components need to be nested in a <SearchHeadlessProvider /> which is imported from @yext/search-headless-react. Under the hood, the Provider utilizes React Context so that all of its child components can have access to SearchHeadless state and actions.
• We could optionally specify a series of props on our <SearchBar />, found in the documentation for the Searchbar Component.
• VerticalResults requires a CardComponent prop. Here, we will use the StandardCard to display the name and description from the entities returned by our searches.

Now, run your app locally and try some searches!

5. Add Analytics

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

6. Next Steps

Explore the library’s documentation.