New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« State SearchProvider »
Elastic Docs ›Search UI ›Architecture ›Configuration

Actions

edit

Actions

edit

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

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

Add a filter in addition to current filters values.

Examples

edit
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

edit
Parameters description

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

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

Set a filter value, replacing current filter values.

Examples

edit
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

edit
Parameters description

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

edit

Removes filters or filter values.

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

Examples

edit
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

edit
Parameters description

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

edit

Reset state to initial search state.

reset();

clearFilters

edit

Clear all filters.

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

Examples

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

Parameters

edit
Parameters description

except

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

setCurrent

edit

Update the current page number. Used for paging.

setCurrent(current: number)

Examples

edit
setCurrent(2);

Parameters

edit
Parameters description

current

Required. Number type. The page number.

setResultsPerPage

edit

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

setResultsPerPage(resultsPerPage: number)

Examples

edit
setResultsPerPage(20);

Parameters

edit
Parameters description

resultsPerPage

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

setSearchTerm

edit
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

edit
setSearchTerm("train");

Parameters

edit
Parameters description

searchTerm

Required. String type. the new search term to query by

options

Optional. Object type. See SetSearchTermOptions type.

SetSearchTermOptions Parameters

edit
Parameters description

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

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

Update the sort option.

Parameters

edit
Parameters description

sort

SortOption or String - field to sort on

sortDirection

String - "asc" or "desc"

trackClickThrough

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

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

Parameters

edit
Parameters description

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

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

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

Parameters

edit
Parameters description

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

edit

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

edit
Parameters description

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

edit
a11yNotify(
  messageFunc: string,
  messageArgs?: unknown
)

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

Parameters

edit
Parameters description

messageFunc

String - object key to run as function

messageArgs

Object - Arguments to pass to form your screen reader message string

Types

edit

FilterValue & FilterType Types

edit

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

Types

edit
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";
« State SearchProvider »
Was this helpful?
Feedback