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

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 Vite Project

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

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.

Remove Default Styles from index.css

Before moving on, make sure your index.css file is empty.

Install Tailwind CSS

To add Tailwind to your project, follow their installation instructions.

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

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

Ready to get your hands dirty? Feel free to play around with the library in this Code Sandbox, explore the library’s documentation.