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 its components, and you can also use it 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 renders:

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 automatically execute searches based on user interaction, there may be times when you need to execute a search without user input. 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 to execute a search when a component mounts:

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 Search UI components.

In this example, the FilterSearch component is modified 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 useSearchActions (often in combination with useSearchState) 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 useSearchActions in the GitHub documentation.