Type to search.

Actions

Serverless

Elastic Cloud Serverless projects are autoscaled environments, fully managed by Elastic and available on Elastic Cloud.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Serverless interfaces and procedures might differ from classic Elastic Stack deployments.

Stack

The Elastic Stack includes Elastic's core products such as Elasticsearch, Kibana, Logstash, and Beats.

Availability

  • Generally available

    This functionality is generally available and ready for production usage.

Unless stated otherwise on the page, this functionality is available when your Elastic Stack is deployed on Elastic Cloud Hosted, Elastic Cloud Enterprise, Elastic Cloud on Kubernetes, and self-managed environments.

This documentation corresponds to the latest patch available for each minor version. If you're not using the latest patch, check the release notes for changes.

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

JavaScript 
setSearchTerm("search term");

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

Jsx 
// 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:

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

This will only result in a single API call.

TypeScript 
addFilter(
  name: string,
  value: FilterValue,
  type: FilterType = "all",
  persistent?: Boolean
)

Add a filter in addition to current filters values.

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

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

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

addFilter("rating", {
  name: "badRating",
  from: 1,
  to: 6
});
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
persistent Optional. Set true, the facet filter will not be cleared when a new search is performed
JavaScript 
setFilter(
  name: string,
  value: FilterValue,
  type: FilterType = "all",
  persistent?: Boolean
)

Set a filter value, replacing current filter values.

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

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

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

setFilter("rating", {
  name: "badRating",
  from: 1,
  to: 6
});
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
persistent Optional. Set true, the facet filter will not be cleared when a new search is performed

Removes filters or filter values.

JavaScript 
removeFilter(
  name: string,
  value?: FilterValue,
  type?: FilterType
)
JavaScript 
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 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 state to initial search state.

JavaScript 
reset();

Clear all filters.

JavaScript 
clearFilters(((except: string[]) = []));
JavaScript 
clearFilters();
clearFilters(["states"]);
  1. field name
Parameters description
except Optional. String array. Field names which you want to ignore being cleared.

Update the current page number. Used for paging.

JavaScript 
setCurrent(current: number)
JavaScript 
setCurrent(2);
Parameters description
current Required. Number type. The page number.

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

JavaScript 
setResultsPerPage(resultsPerPage: number)
JavaScript 
setResultsPerPage(20);
Parameters description
resultsPerPage Required. Number type. Sets number of results per page.
JavaScript 
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.

JavaScript 
setSearchTerm("train");
Parameters description
searchTerm Required. String type. the new search term to query by
options Optional. Object type. See SetSearchTermOptions type.
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.
JavaScript 
setSort(
  sort: SortOption[] | string,
  sortDirection: SortDirection
)

Update the sort option.

Parameters description
sort SortOption or String - field to sort on
sortDirection String - "asc" or "desc"
JavaScript 
trackClickThrough(
  documentId: string,
  tags: string[] = []
)

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

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
JavaScript 
trackAutocompleteClickThrough(
  documentId: string,
  tags: string[] = []
)

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

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
Note

This action requires the use of the analytics plugin.

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

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

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
JavaScript 
a11yNotify(
  messageFunc: string,
  messageArgs?: unknown
)

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

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

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

TypeScript 
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";