Quick Start - Yext Pages | Yext Hitchhikers Platform

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:

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

book
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;
book
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. Next Steps

Explore the library’s documentation , and check out the inspiration hub for other examples using the component library.

Feedback