Sitewide search

EuiSelectableTemplateSitewide is an opinionated wrapper around

EuiSelectable to provide a reusable template across the Elastic products that will share the same global search capabilities. It creates the search input that triggers a popover containing the list of options.

Basic setup

Search input

The search ability of EuiSelectable is still hooked up to the options provided. It will highlight the portion of the label that matches the search string.

The demo showcases the possibility to allow a keyboard shortcut (command + K) to trigger the search input focus, but the template does not come with this ability.

The popover itself allows you to display a

popoverTitle node, popoverFooter node, or pass any of the popoverProps to the EuiPopover component.

Selection

The options themselves are simply rendered as list items with no interactive behavior like buttons or links. You must handle the interaction when the component passes back the altered array of options with the selected option having checked: 'on'.

The default display is to render the search input inline which triggers a popover with the results. Or you can decide to trigger the whole selectable component from a single button. By passing your own button to popoverButton, the component will use this to trigger the popover, putting the search inside.

This is a great way to handle reducing the size of the component for smaller screens. The component offers a helper prop called popoverButtonBreakpoints which will only render the popoverButton if the window size matches named breakpoint(s).

Options

The options are the most opinionated portion of the template. Their display is determined by the props passed in and extends the normal EuiSelectable.option type. All parts are optional with the exception of the label (A).

A. LabelD. MetaDeploymentDefault display

Code snippet

✄𐘗tsx code block:
✄𐘗const options: EuiSelectableTemplateSitewideOption[] = [
  {
    label: 'Label',
    icon: {
      type: 'logoKibana'
    }
    avatar: {
      name: 'Default',
    },
    meta: [
      {
        text: 'Meta',
        type: 'application',
      },
      {
        text: 'Deployment',
        type: 'deployment',
      },
      {
        text: 'Default display',
      },
    ],
  },
]

label (required): The name of the item itself. By default, the search box will only use this to match the search term against, but you can supply a separate searchableLabel that combines the label and meta data to search on.
icon: Only display the solution or application's logo when the option links to the application itself (Dashboard app) and not lower-level items such as individual dashboards. Size and color are predetermined but can be overridden.
avatar: Represents the Kibana Space that the item is located in, if multiple spaces are present. Type and size are predetermined but can be overridden.
meta: This bottom line should only contain items if the option is a lower-level item (individual dashboard). The display of which defaults to simple text, but if you pass one of the predetermined types, they will be styled according to the design pattern.

The demo shows how you can temporarily replace the icon for a subset of options to display a short list of recently viewed options.

Props

EuiSelectableTemplateSitewide

Extends HTMLAttributes


Prop	Description and type	Default value
Prop options#	Description and type Extends the typical #EuiSelectableTemplateSitewideOption with the addition of pre-composed elements such as `icon`, `avatar`and `meta` Type: `EuiSelectableTemplateSitewideOption[]`	Default value Required
Prop children#	Description and type Function that takes the `list` node and then the `search` node (if `searchable` is applied) Type: `(list: ReactElement<typeof EuiSelectableList \| FunctionComponent<EuiSelectableMessageProps>, string \| JSXElementConstructor<any>>, search: ReactElement<...>) => ReactNode`	Default value
Prop className#	Description and type Type: `string`	Default value
Prop css#	Description and type Type: `Interpolation<Theme>`	Default value
Prop height#	Description and type Sets the max height in pixels or pass `full` to allow the whole group to fill the height of its container and allows the list grow as well Type: `number \| "full"`	Default value
Prop isLoading#	Description and type Show an loading indicator while you load and hook up your data Type: `boolean`	Default value
Prop aria-label#	Description and type Defines a string value that labels the current element. @see aria-labelledby. Type: `string`	Default value
Prop data-test-subj#	Description and type Type: `string`	Default value
Prop onChange#	Description and type Passes back the altered `options` array with selected options having `checked: 'on'`. Also passes back the React click/keyboard event as a second argument, and the option that triggered the onChange event as a third argument. Type: `(options: ((DisambiguateSet<EuiSelectableGroupLabelOption<{ [key: string]: any; }>, EuiSelectableLIOption<{ [key: string]: any; }>> & CommonProps & { ...; } & HTMLAttributes<...> & { ...; }) \| (DisambiguateSet<...> & ... 3 more ... & { ...; }))[], event: EuiSelectableOnChangeEvent, changedOption: (DisambiguateSet<.....`	Default value
Prop renderOption#	Description and type Custom render function for each option. Returns `(option, searchValue)` Type: `(option: (DisambiguateSet<EuiSelectableGroupLabelOption<{ [key: string]: any; }>, EuiSelectableLIOption<{ [key: string]: any; }>> & CommonProps & { ...; } & HTMLAttributes<...> & { ...; }) \| (DisambiguateSet<...> & ... 3 more ... & { ...; }), searchValue: string) => ReactNode`	Default value
Prop singleSelection#	Description and type Sets the single selection policy of `false`: allows multiple selection `true`: only allows one selection `always`: can and must have only one selection Type: `boolean \| "always"`	Default value
Prop optionMatcher#	Description and type Optional custom option matcher function @example const exactEqualityMatcher: EuiSelectableOptionMatcher = ({ option, searchValue }) => { return option.label === searchValue; } Type: `EuiSelectableOptionMatcher<{ [key: string]: any; }>`	Default value
Prop searchable#	Description and type Hooks up a search box to filter the list (boolean) Type: `boolean`	Default value
Prop searchProps#	Description and type Passes props down to the `EuiFieldSearch`. See #EuiSelectableSearchProps Type: `Partial<EuiSelectableSearchProps<{ [key: string]: any; }>>`	Default value
Prop onActiveOptionChange#	Description and type Passes back the current active option whenever the user changes the currently highlighted option via keyboard navigation or searching. Type: `(option: (DisambiguateSet<EuiSelectableGroupLabelOption<{}>, EuiSelectableLIOption<{}>> & CommonProps & { ...; } & HTMLAttributes<...>) \| (DisambiguateSet<...> & ... 2 more ... & { ...; })) => void`	Default value
Prop allowExclusions#	Description and type Allows marking options as `checked='off'` as well as `'on'` Type: `boolean`	Default value
Prop listProps#	Description and type See #EuiSelectableOptionsListProps Type: `EuiSelectableOptionsListPropsWithDefaults`	Default value
Prop loadingMessage#	Description and type Customize the loading message. Pass a string to simply change the text, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop noMatchesMessage#	Description and type Customize the no matches message. Pass a string to simply change the text, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop emptyMessage#	Description and type Customize the empty message. Pass a string to simply change the text, or a node to replace the whole content. Type: `string \| ReactElement`	Default value
Prop errorMessage#	Description and type Add an error message. The message will be shown when the value is not `null` or `undefined`. Pass a string to simply change the text, or a node to replace the whole content. `errorMessage={hasErrors ? 'My error message' : null}` Type: `string \| ReactElement`	Default value
Prop isPreFiltered#	Description and type Control whether or not options get filtered internally (i.e., whether filtering is handled by EUI or by you, the consumer). If set to `true`, all passed `options` will be displayed regardless of the user's search input. Additionally allows passing a configuration object which enables turning off search highlighting if needed. Type: `boolean \| { highlightSearch?: boolean; }`	Default value `false`
Prop selectableScreenReaderText#	Description and type Optional screen reader instructions to announce upon focus/interaction. This text is read out after the `EuiSelectable` label and a brief pause, but before the default keyboard instructions for interacting with a selectable are read out. Type: `string`	Default value
Prop popoverProps#	Description and type Override some of the EuiPopover props housing the list. The default width is `600` Type: `Partial<Props> & { width?: Width<string \| number>; }`	Default value
Prop popoverTitle#	Description and type Optionally provide a title for the popover Type: `ReactNode`	Default value
Prop popoverFooter#	Description and type Optionally provide a footer for the popover Type: `ReactNode`	Default value
Prop popoverButton#	Description and type Optionally provide a separate button for toggling the display of the popover. Type: `ReactElement`	Default value
Prop popoverButtonBreakpoints#	Description and type Pass an array of named breakpoints for which to show the `popoverButton`. If `undefined`, the `popoverButton` will always show (if provided) Type: `string[]`	Default value

Basic setup.css-1pgbpvp{-webkit-margin-start:8px;margin-inline-start:8px;opacity:0;}.css-1pgbpvp:focus,.heading:hover .css-1pgbpvp{opacity:1;}

Search input

Popover

Selection

Popover toggle and responsiveness

Options

Props

Basic setup