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

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)

Initialize Next JS Project

To initialize a Next.js project, follow the instructions on their website.

We recommend selecting the following properties during initialization:

• Would you like to use ESLint with this project? Yes
• Would you like to use Tailwind CSS with this project? Yes
• Would you like to use src/ directory with this project? Yes
• Would you like to use experimental app/ directory with this project? No
• What import alias would you like configured? (leave blank)

Don’t want to use Tailwind CSS? Select No when prompted above and check out the Styling Without Tailwind reference doc.

1. 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

2. Configure Styling

The Search React UI components work best with Tailwind CSS, however you can use whatever CSS framework you choose.

Make sure your pages/styles/globals.css looks like this:

@tailwind base;
@tailwind components;
@tailwind utilities;

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

3. Add the Search Headless Provider

Wrapping your App with the Search Headless Provider

Next, we’ll import and use the library! 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.

Wrap your App with the <SearchHeadlessProvider /> in whichever file is the entry point of your app:

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.

// main.tsx
// Using React 17

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

export default function Home() {
  const config: HeadlessConfig = {
    apiKey: "YOUR API KEY",
    experienceKey: "YOUR EXPERIENCE KEY",
    locale: "en",
    verticalKey: "YOUR VERTICAL KEY",
  };
  
  const searcher = provideHeadless(config);
  return (
  <React.StrictMode>
    <SearchHeadlessProvider searcher={searcher}>
      {/* YOUR CODE HERE */}
    </SearchHeadlessProvider>
  </React.StrictMode>
  )
}

Using a Sandbox account

Using a Sandbox account? Check out this doc.

4. Create a Search Page

Now we can add our components! Let’s start with a basic vertical results page including a search bar and some vertical results:

// App.tsx
// Using React 18

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

const App = (): JSX.Element => {
  return (
    <div className="flex justify-center px-4 py-6">
      <div className="w-full max-w-5xl">
        <SearchBar />
        <VerticalResults CardComponent={StandardCard} />
      </div>
    </div>
  );
};

export default App;

Now, run your app locally by typing npm run dev in the terminal 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.