Configure Your Project for Search | Yext Hitchhikers Platform

What You’ll Learn

In this section, you will:

• Add Search to your Yext account
• Learn how Search UI React helps you build store locators in a Pages project
• Add Search UI React to your project

Overview

The Yext platform enables you to quickly and easily add Search to your site. Once the Yext Search API is enabled and configured for a Yext account, you can start using it in a Pages project with the Search UI React library.

In this unit, you will configure your Yext account for search and install the dependencies needed for Search UI React. You’ll have a filter search bar like the following:

Prerequisites

This module assumes you have a working version of Turtlehead Tacos based off of pages-starter-react-locations . If you need to set that up, run yext pages new and choose “Locations Starter (Basic)”. Be sure to populate your Content with seed data when prompted.

1. Configure Search in your Yext Account

Only a few steps are required to build a simple Search experience:

1. From within your Yext account, click Search in the navigation bar and then click All Search Experiences.
2. Add a Search experience. If you already have a search experience, you will see a button in the top right to Add Experience. If you do not have any experiences, you will be prompted to Create Search Experience.
3. Under Experience Name, enter “Turtlehead Tacos Locator”. The Experience ID will be automatically generated, and you can leave it untouched. Then, click Save.
4. You will then be brought to the Home screen for your new experience. In the left sidebar, click Verticals (under the Configuration section).
5. Click Add Vertical and select the entity types to include in your search experience. For our purposes, we only require Locations, so you can leave all the other entity types unchecked.
6. Click Add Vertical. Then, click Save at the bottom of the screen.

7. Once your search is created, you can make numerous customizations through the Configuration UI or through JSON configuration. In the left sidebar of your newly created experience, click Edit as JSON and add builtin.location as a static filter to the searchable fields in the Locations vertical:

   "verticals": {
     "locations": {
     "entityTypes": [
       "location"
     ],
     "name": "Locations",
     "searchableFields": {
       "builtin.location": {        // New
         "staticFilter": true       // New
       }                            // New
     },
     "sortBys": [],
     "source": "YEXT"
     }
   }

Most store locators use filter search instead of a natural language search bar. You can learn more about filter search  here .

2. Install Search UI React and Add Styling

In the terminal, add the Search UI React library to your application with the following command:

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

To learn more about these Yext-based tools, check out these docs .

The Search UI components require a bit of extra styling configuration. Open tailwind.config.ts and make sure your file looks the same as below:

// tailwind.config.ts

import type { Config } from "tailwindcss";

import { ComponentsContentPath } from "@yext/search-ui-react"; 

export default {
  content: [
    "./src/**/*.{html,js,jsx,ts,tsx}",
    ComponentsContentPath
  ],
  theme: {
    extend: {
      colors: {
        orange: "#ff9500",
        "dark-orange": "#db8000",
      },
      scale: {
        1.02: "1.02",
      },
    },
  },
  plugins: [],
} satisfies Config;

3. Add a Locator Template

You need a new static template where you will eventually add your store locator component. In src/templates, add a new file called locator.tsx and paste the following code:

Note

Be sure to add your search API Key to a .env file and call it YEXT_PUBLIC_SEARCH_API_KEY. You can find this by navigating to Search > Turtlehead Tacos Locator > General Settings within the platform.

// locator.tsx

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

export const getPath: GetPath<TemplateProps> = () => {
  return `locator`;
};

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

const searcher = provideHeadless({
  apiKey: YEXT_PUBLIC_SEARCH_API_KEY,
  // make sure your experience key matches what you see in the platform
  experienceKey: "turtlehead-tacos-locator",
  locale: "en",
  environment: Environment.SANDBOX,
  verticalKey: "locations",
});

const Locator: Template<TemplateRenderProps> = ({ __meta, document }) => {
  return (
    <PageLayout templateData={{ __meta, document }}>
      <SearchHeadlessProvider searcher={searcher}>
        <div className="mx-auto max-w-7xl px-4">
          <FilterSearch
            placeholder="Find Locations Near You"
            searchFields={[
              {
                entityType: "location",
                fieldApiName: "builtin.location",
              },
            ]}
          />
        </div>
      </SearchHeadlessProvider>
    </PageLayout>
  );
};

export default Locator;

There’s a lot going on here so let’s review what you just added:

• You imported provideHeadless and SearchHeadlessProvider from @yext/search-headless-react. provideHeadless will instantiate a new SearchHeadless instance for your project. Passing this as the searcher prop to SearchHeadlessProvider will ensure that any child components of the provider will have access to the Search state.

• Since you are using a Sandbox account for the Pages track, you also need to pass the Sandbox environment to provideHeadless. This will ensure that the correct Search endpoints are used when calling the Search APIs.

  

  Note

  If you are building a locator for a Production account, be sure to remove environment: Environment.SANDBOX from the configuration you are passing to provideHeadless.

• By providing ‘locations’ as the verticalKey, all vertical query requests will be made on the Locations vertical.

You’re going to move FilterSearch into a separate component in the next unit, but it’s here for now for you to test that everything is working properly. If your site isn’t running locally already, enter npm run dev in the terminal and go to the locator page. Try typing in the filter search bar.