useSearchActions | Yext Hitchhikers Platform

useSearchActions is a hook that allows you to dispatch actions using the SearchHeadless instance. These include performing searches, getting autocomplete suggestions, and adding filters. The Search UI React library uses useSearchActions under the hood in many of the components and it can also be used in custom components.

useSearchActions MUST be used in a component that is wrapped in a SearchHeadlessProvider .

Basic Example

This sample component uses searchActions to set the verticalKey and limit in the SearchHeadless state when the component is rendered.

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

const SearchComponent = () => {
  const searchActions = useSearchActions();

  useEffect(() => {
    searchActions.setVertical("products");
    searchActions.setVerticalLimit(5);
  }, []);

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

Executing Search Queries

While many Search UI components will automatically execute searches based on user interaction, there may be times when you need to execute a search without user input. In these cases, you can use useSearchActions to trigger a search in response to other events or data changes in your application.

In this example, search parameters are pulled from the URL in order to execute a search as a component is mounted:

import { useSearchActions } from "@yext/search-headless-react";
import { useEffect } from "react";

const SearchComponent = () => {
  const searchActions = useSearchActions();

  useEffect(() => {
    const urlParams = new URLSearchParams(window.location.search);
    const verticalKey = urlParams.get("verticalKey");
    const query = urlParams.get("query");

    searchActions.setQuery(query || "");

    if (verticalKey) {
      searchActions.setVertical(verticalKey);
      searchActions.executeVerticalQuery();
    } else {
      searchActions.executeUniversalQuery();
    }
  }, []);

  // other code...
}

Extending Search UI Component Functionality

useSearchActions can be used to extend or override the functionality of some of the Search UI components.

In this example, the FilterSearch component is modified in order to run a vertical search on locations based on a static filter:

import {
  FilterSearch,
  OnSelectParams,
} from "@yext/search-ui-react";
import {
  Matcher,
  SelectableStaticFilter,
  useSearchActions,
} from "@yext/search-headless-react";
import { useEffect } from "react";

const StoreLocator = (): JSX.Element => {
  const searchActions = useSearchActions();

  useEffect(() => {
    searchActions.setVertical("locations");
  }, []);

  const handleFilterSelect = (params: OnSelectParams) => {
    const locationFilter: SelectableStaticFilter = {
      selected: true,
      filter: {
        kind: "fieldValue",
        fieldId: params.newFilter.fieldId,
        value: params.newFilter.value,
        matcher: Matcher.Equals,
      },
    };
    searchActions.setStaticFilters([locationFilter]);
    searchActions.executeVerticalQuery();
  };

  return (
    <div>
      <FilterSearch
        onSelect={handleFilterSelect}
        placeholder="Find Locations Near You"
        searchFields={[
          {
            entityType: "location",
            fieldApiName: "builtin.location",
          },
        ]}
      />
      {/* other code... */}
    </div>
  );
};

Creating Custom UI Components

You can use the useSearchState hook (often in combination with the useSearchActions hook) to create your own Search UI components. The Building a Custom Facet Component guide walks you through how to build your own facet component with hooks.

API Reference

You can see a complete list of the functions exposed by the useSearchActions hook here .

Back

< useSearchState

Search Result Typing >

Feedback

<% elem.innerText %>