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.

note

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.

Popover

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'.

Popover toggle and responsiveness

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).

Loading...

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).

B

A. LabelD. MetaDeploymentDefault display

C

Code snippet

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.

note

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 InputHTMLAttributes

𐘂𐘂

✄𐘗✄𐘗

Prop ↦	Description and type ↦	Default value ↵
Prop options# ↦	Description and type Extends the typical EuiSelectable #Options with the addition of pre-composed elements such as icon, avatarand 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 #EuiSelectableOptionsList 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 ↵

𐘂𐘂