Search UI SDK Setup – Yext Help

Search UI is a JavaScript SDK that helps you build search experiences on top of the Yext Search product.

Note: These docs reference version 1.8.0. For older versions, visit the GitHub repository and select the desired version's tag.

Get Started

Looking to quickly try out a Search experience? The following example uses a basic test account. If you'd like to use your own, replace apiKey, experienceKey, and businessId with your own values.

Note: If you are hosting data in the EU cloud region, update the code snippets based on the callouts in the Hosting Data in the EU Cloud Region section.

CSS

Copy-paste the stylesheet <link> into your <head> before all other stylesheets to load the CSS.

<link
  rel="stylesheet"
  type="text/css"
  href="https://assets.sitescdn.net/answers/v1.17/answers.css"
/>

JS

Next, add the JS lib. Place the following <script> in your <head> tag.

<script src="https://assets.sitescdn.net/answers/v1.17/answers.min.js"></script>

HTML

Next, place some <div>s in your page's <body>. These <div>s have class names that match those specified in the component configuration, and is where the library will place the components.

<div class="answers-layout">
  <div class="search-bar"></div>
  <div class="spell-check"></div>
  <div class="direct-answer"></div>
  <div class="universal-results"></div>
  <div class="location-bias"></div>
</div>

Initialize the Library

Initialize the JS lib with an apiKey, experienceKey, and businessId, and add the components to the page:

<script>
ANSWERS.init({
  apiKey: "3517add824e992916861b76e456724d9",  //sample test experience
  experienceKey: "answers-js-docs", //sample test experience
  businessId: "3215760",  //sample test experience
  experienceVersion: "PRODUCTION",
  onReady: function () {
    this.addComponent("SearchBar", {
      container: ".search-bar"
    });
    this.addComponent("SpellCheck", {
      container: ".spell-check"
    });
    this.addComponent("DirectAnswer", {
      container: ".direct-answer"
    });
    this.addComponent("UniversalResults", {
      container: ".universal-results"
    });
    this.addComponent("LocationBias", {
      container: ".location-bias"
    });
  }
});
</script>

Starter Template

Put it all together — your page should look like this:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="X-UA-Compatible" content="ie=edge" />
    <title>Search Test Experience</title>
    <!-- Search CSS-->
    <link
      rel="stylesheet"
      type="text/css"
      href="https://assets.sitescdn.net/answers/v1.17/answers.css"
    />

    <!-- Search Layout styling -->
    <style>
      .answers-layout {
        max-width: 50rem;
        margin: auto;
      }
    </style>

    <!-- Search JS-->
    <script src="https://assets.sitescdn.net/answers/v1.17/answers.min.js"></script>
  </head>
  <body>
    <div class="answers-layout">
      <div class="search-bar"></div>
      <div class="spell-check"></div>
      <div class="direct-answer"></div>
      <div class="universal-results"></div>
      <div class="location-bias"></div>
    </div>

    <script>
      ANSWERS.init({
        apiKey: "3517add824e992916861b76e456724d9",  //sample test experience
        experienceKey: "answers-js-docs",  //sample test experience
        businessId: "3215760",  //sample test experience
        experienceVersion: "PRODUCTION",
        onReady: function () {
          this.addComponent("SearchBar", {
            container: ".search-bar"
          });
          this.addComponent("SpellCheck", {
            container: ".spell-check"
          });
          this.addComponent("DirectAnswer", {
            container: ".direct-answer"
          });
          this.addComponent("UniversalResults", {
            container: ".universal-results"
          });
          this.addComponent("LocationBias", {
            container: ".location-bias"
          });
        }
      });
    </script>
  </body>
</html>

Here is a fully working example:

https://codesandbox.io/embed/suspicious-roentgen-fgmjl?codemirror=1&fontsize=13&hidenavigation=1&theme=dark&view=preview

Search Initialization

Adding the Search UI SDK to a page is a two-step process: initialize the library, then add components.

Basic Initialization

Initialize the library using the ANSWERS.init command. At a minimum, apiKey, experienceKey, businessId, and experienceVersion must be specified.

ANSWERS.init({
  apiKey: "3517add824e992916861b76e456724d9",
  experienceKey: "answers-js-docs",
  businessId: "3215760",
  experienceVersion: "PRODUCTION",
  onReady: function() {
    // ADD COMPONENTS HERE
  },
});

The onReady property is used to add components.

Search Initialization API

Property	Type	Default	Description
apiKey	string		REQUIRED. Your API key.
experienceKey	string		REQUIRED. Your Search experience key.
onReady	function	function() {}	REQUIRED. Invoked when the Answers component library is loaded/ready.
businessId	string		Yext businessId, strongly encouraged to send analytics requests.
useTemplates	boolean	true	If false, don't fetch pre-made templates. Only use this if you plan to implement custom renders for every component.
templateBundle	object		If `useTemplates` is `false`, provide the precompiled templates here.
locale	string	en	The locale of the configuration. Passed to the API request; affects how queries are interpreted and results returned.
experienceVersion	string	PRODUCTION	The Answers Experience version to use for API requests. Can be a label or version number.
debug	boolean		Prints full Answers error details when set to `true`.
sessionTrackingEnabled	boolean	true	If true, the search session is tracked using session storage and cookies. If false, there is no tracking.
disableCssVariablesPonyfill	boolean		Opt-out of automatic CSS variable resolution on init for legacy browsers.
onStateChange	function	function() {}	Invoked when the state of any component changes.
onVerticalSearch	function	function() {}	Analytics callback after a vertical search. See onVerticalSearch Configuration.
onUniversalSearch	function	function() {}	Analytics callback after a universal search. See onUniversalSearch Configuration.
search	object		Search-specific settings.
verticalPages	array		Configuration for each vertical shared across components. See verticalPages Initialization.
navigation	object		DEPRECATED. Use `verticalPages` instead.
verticalKey	string		The vertical key to use for searches. Required if a `defaultInitialSearch` is supplied.
limit	string	20	The number of results to display per page. Maximum is 50.
defaultInitialSearch	string		A default search to use on page load when the user hasn't provided a query. If set to `""`, the `SearchBar`'s `allowEmptySearch` must be set to `true`.
environment	string	production	Either `"production"` or `"sandbox"` depending on your Yext account type.
cloudRegion	string	us	The cloud region for the experience. Either `"us"` or `"eu"`.
cloudChoice	string	multi	The cloud provider. Either `"multi"` or `"gcp"`.

verticalPages Initialization

verticalPages is included in the initialization and is used in components that require information about vertical search pages, including Navigation, Universal Results, and No Results in Vertical Results. It takes an array of objects, each representing a vertical search page.

ANSWERS.init({
  apiKey: "3517add824e992916861b76e456724d9",
  experienceKey: "answers-js-docs",
  businessId: "3215760",
  experienceVersion: "PRODUCTION",
  verticalPages: [
    {
      label: "Home",
      url: "index.html",
      icon: "star",
      isFirst: true,
      isActive: true,
      hideInNavigation: false
    },
    {
      label: "Locations",
      url: "/locations.html",
      verticalKey: "locations",
      icon: "pin",
      isFirst: false,
      isActive: false,
      hideInNavigation: false
    },
    // Other pages here
  ],
  onReady: function() {
    // ADD COMPONENTS HERE
  },
});

Where Is It Used?

Option	No Results	`UniversalResults`	`Navigation`
`label`	Used in alternative verticals	Not used	Used as tab label
`url`	Used in alternative verticals	Used in "View More" link if not specified	Used as tab URL
`icon`	Used in alternative verticals	Not used	Not used
`isFirst`	Not used	Not used	Used to determine which tab is pinned to the first slot
`isActive`	Not used	Not used	Used to determine which tab gets active state
`hideInNavigation`	Not used	Not used	Used to determine which tabs are hidden

Recommended Configuration

isFirst and isActive: The navigation component should ideally always display universal search as the first tab (isFirst), and the current page as active (isActive). It is therefore recommended that your universal tab is always set to isFirst: true on each page, and the current page is set to isActive: true.

hideInNavigation: If you have a vertical you would like to remove from the navigation but still maintain a page for, toggle hideInNavigation as needed. All other configuration will still be passed to the Navigation, No Results, and UniversalResults components.

Example

https://codesandbox.io/embed/competent-cartwright-0qcyz?codemirror=1&fontsize=13&hidenavigation=1&theme=dark&view=preview

verticalPages Initialization API

Property	Type	Description
label	string	REQUIRED. The label for this page, used in both the `Navigation` and no results.
url	string	REQUIRED. The link to this page, used in `Navigation`, no results, and `UniversalResults`.
verticalKey	string	The verticalKey. Required for vertical search pages; must be omitted for universal search.
icon	string	The icon associated with this vertical, used in no results.
iconUrl	string	The URL of the icon associated with this vertical, used in no results. Takes precedence over `icon`.
isFirst	boolean	If true, will show this page first in `Navigation`.
isActive	boolean	If true, will add active styling to this page in `Navigation`.
hideInNavigation	boolean	If true, hide this tab in the `Navigation`.

Versions

The Search UI SDK library uses semantic versioning. You can see a log of all releases in the releases section on GitHub.

Asset Bundles

Note: If you are hosting data in the EU cloud region, replace all references to https://assets.sitescdn.net with https://assets.eu.sitescdn.net.

Full Search UI SDK Assets

The Search UI SDK includes the following assets:

JS (IIFE): https://assets.sitescdn.net/answers/v1/answers.min.js
Templates (UMD): https://assets.sitescdn.net/answers/v1/answerstemplates.compiled.min.js
CSS: https://assets.sitescdn.net/answers/v1/answers.css

Additional assets you can substitute based on your script loader and polyfill needs:

JS (UMD): https://assets.sitescdn.net/answers/v1/answers-umd.min.js
JS (UMD) without polyfills: https://assets.sitescdn.net/answers/v1/answers-modern.min.js
Templates (IIFE): https://assets.sitescdn.net/answers/v1/answerstemplates-iife.compiled.min.js — reference using templateBundle: TemplateBundle instead of templateBundle: TemplateBundle.default in your init.

Searchbar Only Assets

A searchbar-only asset is also available, containing only the necessary JS/CSS/hbs for the SearchBar component. Use this when adding just a search bar to the page.

JS (IIFE): https://assets.sitescdn.net/answers-search-bar/v1/answers.min.js
JS (UMD): https://assets.sitescdn.net/answers-search-bar/v1/answers-umd.min.js
JS (UMD without polyfills): https://assets.sitescdn.net/answers-search-bar/v1/answers-modern.min.js
Templates (UMD): https://assets.sitescdn.net/answers-search-bar/v1/answerstemplates.compiled.min.js
Templates (IIFE): https://assets.sitescdn.net/answers-search-bar/v1/answerstemplates-iife.compiled.min.js — reference using templateBundle: TemplateBundle instead of templateBundle: TemplateBundle.default in your init.
CSS: https://assets.sitescdn.net/answers-search-bar/v1/answers.css