Show a Facet filter for a particular field.

Must configure the corresponding field in the SearchProvider facets object.

Example

import { Facet } from "@elastic/react-search-ui";
import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";

...

<SearchProvider config={{
  ...otherConfig,
  searchQuery: {
    facets: {
     states: { type: "value", size: 30 }
    }
  }
}}>
  {() => (
    <Facet field="states" label="States" view={MultiCheckboxFacet} />
  )}
</SearchProvider>

Example of an OR based Facet filter

Certain configuration of the Facet Component will require a "disjunctive" facet to work correctly. "Disjunctive" facets are facets that do not change when a selection is made. Meaning, all available options will remain as selectable options even after a selection is made.

import { Facet } from "@elastic/react-search-ui";
import { MultiCheckboxFacet } from "@elastic/react-search-ui-views";

...

<SearchProvider config={{
  ...otherConfig,
  searchQuery: {
    disjunctiveFacets: ["states"],
    facets: {
     states: { type: "value", size: 30 }
    }
  }
}}>
  {() => (
    <Facet field="states" label="States" view={MultiCheckboxFacet} filterType="any" />
  )}
</SearchProvider>

Properties

NameDescription
className
field
Field name corresponding to this filter. This requires that the corresponding field has been configured in facets on the top level Provider.
filterType
The type of filter to apply with the selected values. I.e., should "all" of the values match, or just "any" of the values, or "none" of the values. Note: See the example above which describes using "disjunctive" facets in conjunction with filterType.
label
A static label to show in the facet filter.
show
The number of facet filter options to show before concatenating with a "Show more" link.
isFilterable
Whether or not to show Facet quick filter.
view
Used to override the default view for this Component. See View customization below.
*
Any other property passed will be passed through and available to use in a Custom View

View customization

A complete guide to view customization can be found in the Customization: Component views and HTML section.

The following properties are available in the view:

NameDescription
className
Passed through from main component.
label
Type: string. Passed through from main component.
onMoreClick
Type: () => void. Used for a "Show more" link. Call this to show more options.
onRemove
Type: (value: FieldValue) => void. Call this when a user removes a facet filter selection. Pass the value from the corresponding selection from options.
onChange
Type: (value: FieldValue) => void. Call this when a user changes a facet filter selection. Pass the value from the corresponding selection from options.
onSelect
Type: (value: FieldValue) => void. Call this when a user adds a facet filter selection. Pass the value from the corresponding selection from options.
options
Type: FacetValue[]. The options to show available for selection for this facet. selected property will be true if this values is selected.
showMore
Type: boolean. Whether or not to show a "Show more" link. If there are no more options available to show, then this will be false.
values
Type: FilterValue[]. A list of all the selected values. This can also be deduced be inspected the selected properties of the options.
showSearch
Type: boolean. Whether or not the compopnent is isFilterable. This would indicates that a filter search box should be shown.
onSearch
Type: (value: string) => void. Call this to filter down the facet options shown. Used if there is a search box shown in relation to showSearch.
searchPlaceholder
Type: string. The placeholder fo show in the filter search box when showSearch is true.

See MultiCheckboxFacet.tsx for an example.

When overriding Facet views, note that there are pre-built options that you can choose from, in addition to providing your own:

import {
  BooleanFacet,
  SingleSelectFacet,
  SingleLinksFacet
} from "@elastic/react-search-ui-views";

// Default out-of-the-box view
<Facet
  field="acres"
  label="Acres"
/>

// Choose an alternate out-of-the-box view
<Facet
  field="acres"
  label="Acres"
  view={SingleSelectFacet}
/>

On this page