docs(EuiSelectable): add optionMatcher section and example

src-docs/src/views/selectable/selectable_example.js

@@ -45,6 +45,9 @@ const truncationSource = require('!!raw-loader!./selectable_truncation');
 import SelectableCustomRender from './selectable_custom_render';
 const selectableCustomRenderSource = require('!!raw-loader!./selectable_custom_render');
 
+import SelectableOptionMatcher from './selectable_option_matcher';
+const selectableOptionMatcherSource = require('!!raw-loader!./selectable_option_matcher');
+
 const props = {
   EuiSelectable,
   EuiSelectableOptionProps,
@@ -526,5 +529,39 @@ export const SelectableExample = {
 </EuiSelectable>`,
       props,
     },
+    {
+      title: 'Custom option matcher',
+      text: (
+        <>
+          <p>
+            When searching for options, <EuiCode>EuiSelectable</EuiCode> uses a
+            partial equality string matcher by default, displaying all options
+            whose labels include the searched string.
+          </p>
+          <p>
+            In rare cases, you may want to customize this behavior. You can do
+            so by passing a custom option matcher function to the{' '}
+            <EuiCode>optionMatcher</EuiCode> prop. The function must be of type{' '}
+            <EuiCode>EuiSelectableOptionMatcher</EuiCode> and return
+            <EuiCode>true</EuiCode> for options that should be visible for given
+            search string.
+          </p>
+        </>
+      ),
+      source: [
+        {
+          type: GuideSectionTypes.TSX,
+          code: selectableOptionMatcherSource,
+        },
+      ],
+      demo: <SelectableOptionMatcher />,
+      snippet: `<EuiSelectable
+  options={[]}
+  onChange={newOptions => setOptions(newOptions)}
+  optionMatcher={optionMatcher}
+>
+  {list => list}
+</EuiSelectable>`,
+    },
   ],
 };

src-docs/src/views/selectable/selectable_option_matcher.tsx

@@ -0,0 +1,71 @@
+import React, { useCallback, useState } from 'react';
+
+import { EuiSelectable, EuiSelectableOption } from '../../../../src';
+import { EuiSelectableOptionMatcher } from '../../../../src/components/selectable/selectable';
+
+export default () => {
+  const [options, setOptions] = useState<EuiSelectableOption[]>([
+    {
+      label: 'Titan',
+      'data-test-subj': 'titanOption',
+    },
+    {
+      label: 'Enceladus is disabled',
+      disabled: true,
+    },
+    {
+      label: 'Mimas',
+      checked: 'on',
+    },
+    {
+      label: 'Dione',
+    },
+    {
+      label: 'Iapetus',
+      checked: 'on',
+    },
+    {
+      label: 'Phoebe',
+    },
+    {
+      label: 'Rhea',
+    },
+    {
+      label:
+        "Pandora is one of Saturn's moons, named for a Titaness of Greek mythology",
+    },
+    {
+      label: 'Tethys',
+    },
+    {
+      label: 'Hyperion',
+    },
+  ]);
+
+  const startsWithMatcher = useCallback<EuiSelectableOptionMatcher<unknown>>(
+    ({ option, searchValue }) => {
+      return option.label.startsWith(searchValue);
+    },
+    []
+  );
+
+  return (
+    <EuiSelectable
+      aria-label="Searchable example"
+      searchable
+      searchProps={{
+        'data-test-subj': 'selectableSearchHere',
+      }}
+      options={options}
+      onChange={(newOptions) => setOptions(newOptions)}
+      optionMatcher={startsWithMatcher}
+    >
+      {(list, search) => (
+        <>
+          {search}
+          {list}
+        </>
+      )}
+    </EuiSelectable>
+  );
+};