Actions

To update the state, you can use actions below. Actions are functions that update the Request State and performs an API request.

setSearchTerm("search term");

To get access to the actions within your component, you must wrap your component with our context HOCs.

// Selects `searchTerm` and `setSearchTerm` for use in Component
withSearch(({ searchTerm, setSearchTerm }) => ({
  searchTerm,
  setSearchTerm
}))(Component);

See WithSearch & withSearch for more information.

There are certain cases where you may need to apply one or more actions at a time. Search UI intelligently batches actions into a single API call.

For example, if you need to apply two filters at once, it is perfectly acceptable to write the following code:

addFilter("states", "Alaska", "any");
addFilter("world_heritage_site", "true");

This will only result in a single API call.

addFilter

addFilter(
  name: string,
  value: FilterValue,
  type: FilterType = "all"
)

Add a filter in addition to current filters values.

Examples

addFilter("states", "Alaska");
addFilter("isPublished", true);
addFilter("rating", 1);

addFilter("states", ["Alaska", "California"], "all");
addFilter("states", ["Alaska", "California"], "any");

addFilter("published",{
  name: "published",
  from: "2020-01-01",
  to: "2020-12-31"
});

addFilter("rating",{
  name: "badRating",
  from: 1,
  to: 6
});

Parameters

Parametersdescription
name
Required. Name of the field
value
Required. Filter Value. See FilterValue type.
type
Optional. Defaults to all. How the filter is applied. Can be one of any, all, none

setFilter

setFilter(
  name: string,
  value: FilterValue,
  type: FilterType = "all"
)

Set a filter value, replacing current filter values.

Examples

setFilter("states", "Alaska");
setFilter("isPublished", true);
setFilter("rating", 1);

setFilter("states", ["Alaska", "California"], "all");
setFilter("states", ["Alaska", "California"], "any");

setFilter("published",{
  name: "published",
  from: "2020-01-01",
  to: "2020-12-31"
});

setFilter("rating",{
  name: "badRating",
  from: 1,
  to: 6
});

Parameters

Parametersdescription
name
Required. Name of the field
value
Required. Filter Value. See FilterValue type.
type
Optional. Defaults to all. How the filter is applied. Can be one of any, all, none

removeFilter

Removes filters or filter values.

removeFilter(
  name: string,
  value?: FilterValue,
  type?: FilterType
)

Examples

removeFilter("states");
removeFilter("states", ["Alaska", "California"]);

removeFilter("published", {
  name: "published",
  from: "2020-01-01",
  to: "2020-12-31"
});

removeFilter("rating", {
  name: "badRating",
  from: 1,
  to: 6
});

Parameters

Parametersdescription
name
Required. Name of the field
value
Optional. Filter Value. Will remove all filters under field if value not specified. See FilterValue type.
type
Optional. Defaults to all. How the filter is applied. Can be one of any, all, none

reset

Reset state to initial search state.

reset();

clearFilters

Clear all filters.

clearFilters((except: string[] = []));

Examples

clearFilters();
clearFilters(["states"]); // field name

Parameters

Parametersdescription
except
Optional. String array. Field names which you want to ignore being cleared.

setCurrent

Update the current page number. Used for paging.

setCurrent(current: number)

Examples

setCurrent(2);

Parameters

Parametersdescription
current
Required. Number type. The page number.

setResultsPerPage

Update the number of results per page. Used for paging.

setResultsPerPage(resultsPerPage: number)

Examples

setResultsPerPage(20);

Parameters

Parametersdescription
resultsPerPage
Required. Number type. Sets number of results per page.

setSearchTerm

setSearchTerm(
  searchTerm: string,
  {
    autocompleteMinimumCharacters = 0,
    autocompleteResults = false,
    autocompleteSuggestions = false,
    shouldClearFilters = true,
    refresh = true,
    debounce = 0
  }: SetSearchTermOptions = {}
)

Update the search term. Also gives you the ability to control autocomplete options.

Examples

setSearchTerm("train");

Parameters

Parametersdescription
searchTerm
Required. String type. the new search term to query by
options
Optional. Object type. See SetSearchTermOptions type.

SetSearchTermOptions Parameters

Parametersdescription
autocompleteMinimumCharacters
Optional. miniumum terms to start performing autocomplete suggestions
autocompleteResults
Optional. To perform autocomplete Results
autocompleteSuggestions
Optional. To perform autocomplete Suggestions
shouldClearFilters
Optional. To clear filters
refresh
Optional. To refresh results
debounce
Optional.

setSort

setSort(
  sort: SortOption[] | string,
  sortDirection: SortDirection
)

Update the sort option.

Parameters

Parametersdescription
sort
SortOption or String - field to sort on
sortDirection
String - "asc" or "desc"

trackClickThrough

trackClickThrough(
  documentId: string,
  tags: string[] = []
)

Report a clickthrough event, which is when a user clicks on a result link.

Parameters

Parametersdescription
documentId
String - The document ID associated with the result that was clicked
tags
Optional. Array[String] Optional tags which can be used to categorize this click event

trackAutocompleteClickThrough

trackAutocompleteClickThrough(
  documentId: string,
  tags: string[] = []
)

Report a clickthrough event, which is when a user clicks on an autocomplete suggestion.

Parameters

Parametersdescription
documentId
String - The document ID associated with the result that was clicked
tags
Optional. Array[String] Optional tags which can be used to categorize this click event

trackAutocompleteSuggestionClickThrough

This action requires the use of the analytics plugin

trackAutocompleteSuggestionClickThrough(
  suggestion: string,
  postion: number
  tags: string[] = []
)

Report a suggestion clickthrough event, which is when a user clicks on an autocomplete suggestion.

Parameters

Parametersdescription
suggestion
String - The suggestion that was clicked
position
Number - The position of the suggestion that was clicked
tags
Optional. Array[String] Optional tags which can be used to categorize this click event

a11yNotify

a11yNotify(
  messageFunc: string,
  messageArgs?: unknown
)

Reads out a screen reader accessible notification. See a11yNotificationMessages under TODO LINK

Parameters

Parametersdescription
messageFunc
String - object key to run as function
messageArgs
Object - Arguments to pass to form your screen reader message string

Types

FilterValue & FilterType Types

FilterValue can be either a value type or a range type.

Types

type FilterValue = FilterValueValue | FilterValueRange;

type FieldValue = string | number | boolean | Array<string | number | boolean>;

type FilterValueValue = FieldValue;

type FilterValueRange = {
  from?: FieldValue;
  name: string;
  to?: FieldValue;
};

type FilterType = "any" | "all" | "none";

On this page