From c9e622e74ff83995e6fa4d03325c7de7a8707510 Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Fri, 27 Jun 2025 20:43:48 +0200
Subject: [PATCH 1/6] refactor(combobox): support custom option ids

- this ensures that consumers can pass custom ids on options without breaking the internal accessibility handling of combobox
---
 .../src/components/combo_box/combo_box.tsx    | 25 ++++++++++++++++---
 .../combo_box_options_list.tsx                |  4 +++
 .../filter_group/filter_select_item.tsx       |  9 ++++++-
 3 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/packages/eui/src/components/combo_box/combo_box.tsx b/packages/eui/src/components/combo_box/combo_box.tsx
index 6e923b9f8e9..0b7815368fa 100644
--- a/packages/eui/src/components/combo_box/combo_box.tsx
+++ b/packages/eui/src/components/combo_box/combo_box.tsx
@@ -212,6 +212,7 @@ interface EuiComboBoxState<T> {
   hasFocus: boolean;
   isListOpen: boolean;
   matchingOptions: Array<EuiComboBoxOptionOption<T>>;
+  listOptions: Array<HTMLButtonElement | null>;
   searchValue: string;
 }
 
@@ -249,6 +250,7 @@ export class EuiComboBox<T> extends Component<
       showPrevSelected: Boolean(this.props.singleSelection),
       sortMatchesBy: this.props.sortMatchesBy,
     }),
+    listOptions: [],
     searchValue: initialSearchValue,
   };
 
@@ -271,6 +273,17 @@ export class EuiComboBox<T> extends Component<
     this.listRefInstance = ref;
   };
 
+  setListOptions = (node: HTMLButtonElement | null, index: number) => {
+    this.setState(({ listOptions }) => {
+      const _listOptions = listOptions;
+      _listOptions[index] = node;
+
+      return {
+        listOptions: _listOptions,
+      };
+    });
+  };
+
   openList = () => {
     this.setState({
       isListOpen: true,
@@ -604,9 +617,10 @@ export class EuiComboBox<T> extends Component<
     if (singleSelection) {
       requestAnimationFrame(() => this.closeList());
     } else {
-      this.setState({
-        activeOptionIndex: this.state.matchingOptions.indexOf(addedOption),
-      });
+      this.setState(({ listOptions, matchingOptions }) => ({
+        listOptions: listOptions.slice(0, matchingOptions.length - 1),
+        activeOptionIndex: matchingOptions.indexOf(addedOption),
+      }));
     }
   };
 
@@ -809,6 +823,7 @@ export class EuiComboBox<T> extends Component<
               isCaseSensitive={isCaseSensitive}
               isLoading={isLoading}
               listRef={this.listRefCallback}
+              setListOptions={this.setListOptions}
               matchingOptions={matchingOptions}
               onCloseList={this.closeList}
               onCreateOption={onCreateOption}
@@ -876,7 +891,9 @@ export class EuiComboBox<T> extends Component<
                     compressed={compressed}
                     focusedOptionId={
                       this.hasActiveOption()
-                        ? this.rootId(`_option-${this.state.activeOptionIndex}`)
+                        ? this.state.listOptions[this.state.activeOptionIndex]
+                            ?.id ??
+                          this.rootId(`_option-${this.state.activeOptionIndex}`)
                         : undefined
                     }
                     fullWidth={fullWidth}
diff --git a/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx b/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
index 3b80aae71a6..46b5cdb94e4 100644
--- a/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
+++ b/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
@@ -65,6 +65,7 @@ export type EuiComboBoxOptionsListProps<T> = CommonProps & {
   isCaseSensitive?: boolean;
   isLoading?: boolean;
   listRef: RefCallback<HTMLDivElement>;
+  setListOptions: (ref: HTMLButtonElement | null, index: number) => void;
   matchingOptions: Array<EuiComboBoxOptionOption<T>>;
   onCloseList: (event: Event) => void;
   onCreateOption?: (
@@ -168,6 +169,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
       searchValue,
       rootId,
       matchingOptions,
+      setListOptions,
     } = this.props;
 
     const optionIndex = matchingOptions.indexOf(option);
@@ -220,6 +222,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
         title={label}
         aria-setsize={matchingOptions.length}
         aria-posinset={optionIndex + 1}
+        forwardRef={(ref) => setListOptions(ref, index)}
         {...rest}
       >
         <span className="euiComboBoxOption__contentWrapper">
@@ -337,6 +340,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
       delimiter,
       truncationProps,
       listboxAriaLabel,
+      setListOptions,
       ...rest
     } = this.props;
 
diff --git a/packages/eui/src/components/filter_group/filter_select_item.tsx b/packages/eui/src/components/filter_group/filter_select_item.tsx
index b7901a8c54a..a43df33777a 100644
--- a/packages/eui/src/components/filter_group/filter_select_item.tsx
+++ b/packages/eui/src/components/filter_group/filter_select_item.tsx
@@ -28,6 +28,7 @@ export interface EuiFilterSelectItemProps
   isFocused?: boolean;
   toolTipContent?: EuiComboBoxOptionOption['toolTipContent'];
   toolTipProps?: EuiComboBoxOptionOption['toolTipProps'];
+  forwardRef?: (ref: HTMLButtonElement | null) => void;
 }
 
 const resolveIconAndColor = (checked?: FilterChecked) => {
@@ -65,6 +66,11 @@ export class EuiFilterSelectItemClass extends Component<
     hasFocus: false,
   };
 
+  setButtonRef = (node: HTMLButtonElement | null) => {
+    this.buttonRef = node;
+    this.props.forwardRef?.(node);
+  };
+
   focus = () => {
     if (this.buttonRef) {
       this.buttonRef.focus();
@@ -95,6 +101,7 @@ export class EuiFilterSelectItemClass extends Component<
       toolTipContent,
       toolTipProps,
       style,
+      forwardRef,
       ...rest
     } = this.props;
 
@@ -140,7 +147,7 @@ export class EuiFilterSelectItemClass extends Component<
 
     const optionItem = (
       <button
-        ref={(ref) => (this.buttonRef = ref)}
+        ref={this.setButtonRef}
         role="option"
         type="button"
         aria-selected={checked === 'on'}

From e408d4744eaf7119b02069f2067499119bea319e Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Fri, 27 Jun 2025 20:44:15 +0200
Subject: [PATCH 2/6] docs(storybook): add separate custom id story

---
 .../combo_box/combo_box.stories.tsx           | 25 +++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/packages/eui/src/components/combo_box/combo_box.stories.tsx b/packages/eui/src/components/combo_box/combo_box.stories.tsx
index 188bdd91389..56712a38a16 100644
--- a/packages/eui/src/components/combo_box/combo_box.stories.tsx
+++ b/packages/eui/src/components/combo_box/combo_box.stories.tsx
@@ -80,6 +80,31 @@ export const Playground: Story = {
   render: (args) => <StatefulComboBox {...args} />,
 };
 
+export const WithCustomOptionIds: Story = {
+  parameters: {
+    controls: {
+      include: ['options', 'selectedOptions', 'onChange'],
+    },
+    // This story is visually effectively the same as Playground
+    loki: { skip: true },
+  },
+  args: {
+    options: [
+      { id: 'item-1', label: 'Item 1' },
+      { id: 'item-2', label: 'Item 2' },
+      { id: 'item-3', label: 'Item 3' },
+      { id: 'item-4', label: 'Item 4', disabled: true },
+      { id: 'item-5', label: 'Item 5' },
+      { id: 'item-6', label: 'Item 6' },
+      { id: 'item-7', label: 'Item 7' },
+      { id: 'item-8', label: 'Item 8' },
+      { id: 'item-9', label: 'Item 9' },
+      { id: 'item-10', label: 'Item 10' },
+    ],
+  },
+  render: (args) => <StatefulComboBox {...args} />,
+};
+
 export const WithTooltip: Story = {
   parameters: {
     controls: {

From 26fab5234a9f5e7a7358f139be9b38cee2d7c26d Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Fri, 27 Jun 2025 20:49:36 +0200
Subject: [PATCH 3/6] test: add accessibility tests

- ensures both usages of ids result in expected accessible markup
---
 .../components/combo_box/combo_box.a11y.tsx   | 164 +++++++++++++-----
 1 file changed, 125 insertions(+), 39 deletions(-)

diff --git a/packages/eui/src/components/combo_box/combo_box.a11y.tsx b/packages/eui/src/components/combo_box/combo_box.a11y.tsx
index e38436d010b..ee24997a2d6 100644
--- a/packages/eui/src/components/combo_box/combo_box.a11y.tsx
+++ b/packages/eui/src/components/combo_box/combo_box.a11y.tsx
@@ -14,50 +14,53 @@ import React, { useState } from 'react';
 import { EuiComboBox, EuiComboBoxOptionOption } from './index';
 
 interface ComboBoxOption {
+  id?: string;
   label: string;
   'data-test-subj': string;
 }
 type ComboBoxOptions = Array<EuiComboBoxOptionOption<ComboBoxOption>>;
 
-const ComboBox = () => {
-  const [options] = useState<ComboBoxOptions>([
-    {
-      label: 'Titan',
-      'data-test-subj': 'titanOption',
-    },
-    {
-      label: 'Enceladus',
-      'data-test-subj': 'enceladusOption',
-    },
-    {
-      label: 'Mimas',
-      'data-test-subj': 'mimasOption',
-    },
-    {
-      label: 'Dione',
-      'data-test-subj': 'dioneOption',
-    },
-    {
-      label: 'Iapetus',
-      'data-test-subj': 'iapetusOption',
-    },
-    {
-      label: 'Phoebe',
-      'data-test-subj': 'phoebeOption',
-    },
-    {
-      label: 'Rhea',
-      'data-test-subj': 'rheaOption',
-    },
-    {
-      label: 'Tethys',
-      'data-test-subj': 'tethysOption',
-    },
-    {
-      label: 'Hyperion',
-      'data-test-subj': 'hyperionOption',
-    },
-  ]);
+const ComboBox = ({ initialOptions }: { initialOptions?: ComboBoxOptions }) => {
+  const [options] = useState<ComboBoxOptions>(
+    initialOptions ?? [
+      {
+        label: 'Titan',
+        'data-test-subj': 'titanOption',
+      },
+      {
+        label: 'Enceladus',
+        'data-test-subj': 'enceladusOption',
+      },
+      {
+        label: 'Mimas',
+        'data-test-subj': 'mimasOption',
+      },
+      {
+        label: 'Dione',
+        'data-test-subj': 'dioneOption',
+      },
+      {
+        label: 'Iapetus',
+        'data-test-subj': 'iapetusOption',
+      },
+      {
+        label: 'Phoebe',
+        'data-test-subj': 'phoebeOption',
+      },
+      {
+        label: 'Rhea',
+        'data-test-subj': 'rheaOption',
+      },
+      {
+        label: 'Tethys',
+        'data-test-subj': 'tethysOption',
+      },
+      {
+        label: 'Hyperion',
+        'data-test-subj': 'hyperionOption',
+      },
+    ]
+  );
 
   const [selectedOptions, setSelected] = useState<ComboBoxOptions>([]);
 
@@ -125,4 +128,87 @@ describe('EuiComboBox', () => {
       cy.checkAxe();
     });
   });
+
+  describe('Manual Accessibility check', () => {
+    it('sets the correct aria-activedescendant id', () => {
+      cy.realPress('Tab');
+      cy.get('input[data-test-subj="comboBoxSearchInput"]').should(
+        'have.focus'
+      );
+      cy.get('button[data-test-subj="titanOption"]').should('exist');
+      cy.realPress('ArrowDown');
+      cy.realPress('ArrowDown');
+      cy.realPress('ArrowDown');
+
+      cy.get('input[data-test-subj="comboBoxSearchInput"]')
+        .invoke('attr', 'aria-activedescendant')
+        .should('include', 'option-2');
+
+      cy.realPress('Enter');
+      cy.realPress('ArrowDown');
+
+      cy.get('input[data-test-subj="comboBoxSearchInput"]')
+        .invoke('attr', 'aria-activedescendant')
+        .should('include', 'option-3');
+    });
+
+    it('sets the correct aria-activedescendant id with custom option ids', () => {
+      cy.realMount(
+        <ComboBox
+          initialOptions={[
+            {
+              id: 'titan',
+              label: 'Titan',
+              'data-test-subj': 'titanOption',
+            },
+            {
+              id: 'enceladus',
+              label: 'Enceladus',
+              'data-test-subj': 'enceladusOption',
+            },
+            {
+              id: 'mimas',
+              label: 'Mimas',
+              'data-test-subj': 'mimasOption',
+            },
+            {
+              id: 'dione',
+              label: 'Dione',
+              'data-test-subj': 'dioneOption',
+            },
+            {
+              id: 'iapetus',
+              label: 'Iapetus',
+              'data-test-subj': 'iapetusOption',
+            },
+          ]}
+        />
+      );
+      cy.get('input[data-test-subj="comboBoxSearchInput"]').should('exist');
+
+      cy.realPress('Tab');
+      cy.get('input[data-test-subj="comboBoxSearchInput"]').should(
+        'have.focus'
+      );
+      cy.get('button[data-test-subj="titanOption"]').should('exist');
+      cy.realPress('ArrowDown');
+      cy.realPress('ArrowDown');
+      cy.realPress('ArrowDown');
+
+      cy.get('input[data-test-subj="comboBoxSearchInput"]').should(
+        'have.attr',
+        'aria-activedescendant',
+        'mimas'
+      );
+
+      cy.realPress('Enter');
+      cy.realPress('ArrowDown');
+
+      cy.get('input[data-test-subj="comboBoxSearchInput"]').should(
+        'have.attr',
+        'aria-activedescendant',
+        'iapetus'
+      );
+    });
+  });
 });

From 623d5a0e785cfc7d2494df7d2f6d0af5cbdacbb3 Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Fri, 27 Jun 2025 21:06:16 +0200
Subject: [PATCH 4/6] chore: add changelog

---
 packages/eui/changelogs/upcoming/8829.md | 4 ++++
 1 file changed, 4 insertions(+)
 create mode 100644 packages/eui/changelogs/upcoming/8829.md

diff --git a/packages/eui/changelogs/upcoming/8829.md b/packages/eui/changelogs/upcoming/8829.md
new file mode 100644
index 00000000000..4edd517c07b
--- /dev/null
+++ b/packages/eui/changelogs/upcoming/8829.md
@@ -0,0 +1,4 @@
+**Accessibility**
+
+- Fixed missing screen reader output for `EuiComboBox` with `options` that have custom `id` attributes
+

From 5f59e08579e8643e1ba206bc53cc609a227e8371 Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Tue, 1 Jul 2025 10:31:43 +0200
Subject: [PATCH 5/6] refactor: update prop and state naming

- updates setListOptions to setListOptionRefs
---
 .../src/components/combo_box/combo_box.tsx    | 25 ++++++++++---------
 .../combo_box_options_list.tsx                |  8 +++---
 2 files changed, 17 insertions(+), 16 deletions(-)

diff --git a/packages/eui/src/components/combo_box/combo_box.tsx b/packages/eui/src/components/combo_box/combo_box.tsx
index 0b7815368fa..c5cfbf33cab 100644
--- a/packages/eui/src/components/combo_box/combo_box.tsx
+++ b/packages/eui/src/components/combo_box/combo_box.tsx
@@ -212,7 +212,7 @@ interface EuiComboBoxState<T> {
   hasFocus: boolean;
   isListOpen: boolean;
   matchingOptions: Array<EuiComboBoxOptionOption<T>>;
-  listOptions: Array<HTMLButtonElement | null>;
+  listOptionRefs: Array<HTMLButtonElement | null>;
   searchValue: string;
 }
 
@@ -250,7 +250,7 @@ export class EuiComboBox<T> extends Component<
       showPrevSelected: Boolean(this.props.singleSelection),
       sortMatchesBy: this.props.sortMatchesBy,
     }),
-    listOptions: [],
+    listOptionRefs: [],
     searchValue: initialSearchValue,
   };
 
@@ -273,13 +273,13 @@ export class EuiComboBox<T> extends Component<
     this.listRefInstance = ref;
   };
 
-  setListOptions = (node: HTMLButtonElement | null, index: number) => {
-    this.setState(({ listOptions }) => {
-      const _listOptions = listOptions;
-      _listOptions[index] = node;
+  setListOptionRefs = (node: HTMLButtonElement | null, index: number) => {
+    this.setState(({ listOptionRefs }) => {
+      const _listOptionRefs = listOptionRefs;
+      _listOptionRefs[index] = node;
 
       return {
-        listOptions: _listOptions,
+        listOptionRefs: _listOptionRefs,
       };
     });
   };
@@ -617,8 +617,8 @@ export class EuiComboBox<T> extends Component<
     if (singleSelection) {
       requestAnimationFrame(() => this.closeList());
     } else {
-      this.setState(({ listOptions, matchingOptions }) => ({
-        listOptions: listOptions.slice(0, matchingOptions.length - 1),
+      this.setState(({ listOptionRefs, matchingOptions }) => ({
+        listOptionRefs: listOptionRefs.slice(0, matchingOptions.length - 1),
         activeOptionIndex: matchingOptions.indexOf(addedOption),
       }));
     }
@@ -823,7 +823,7 @@ export class EuiComboBox<T> extends Component<
               isCaseSensitive={isCaseSensitive}
               isLoading={isLoading}
               listRef={this.listRefCallback}
-              setListOptions={this.setListOptions}
+              setListOptionRefs={this.setListOptionRefs}
               matchingOptions={matchingOptions}
               onCloseList={this.closeList}
               onCreateOption={onCreateOption}
@@ -891,8 +891,9 @@ export class EuiComboBox<T> extends Component<
                     compressed={compressed}
                     focusedOptionId={
                       this.hasActiveOption()
-                        ? this.state.listOptions[this.state.activeOptionIndex]
-                            ?.id ??
+                        ? this.state.listOptionRefs[
+                            this.state.activeOptionIndex
+                          ]?.id ??
                           this.rootId(`_option-${this.state.activeOptionIndex}`)
                         : undefined
                     }
diff --git a/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx b/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
index 46b5cdb94e4..c5a9915fbdc 100644
--- a/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
+++ b/packages/eui/src/components/combo_box/combo_box_options_list/combo_box_options_list.tsx
@@ -65,7 +65,7 @@ export type EuiComboBoxOptionsListProps<T> = CommonProps & {
   isCaseSensitive?: boolean;
   isLoading?: boolean;
   listRef: RefCallback<HTMLDivElement>;
-  setListOptions: (ref: HTMLButtonElement | null, index: number) => void;
+  setListOptionRefs: (ref: HTMLButtonElement | null, index: number) => void;
   matchingOptions: Array<EuiComboBoxOptionOption<T>>;
   onCloseList: (event: Event) => void;
   onCreateOption?: (
@@ -169,7 +169,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
       searchValue,
       rootId,
       matchingOptions,
-      setListOptions,
+      setListOptionRefs,
     } = this.props;
 
     const optionIndex = matchingOptions.indexOf(option);
@@ -222,7 +222,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
         title={label}
         aria-setsize={matchingOptions.length}
         aria-posinset={optionIndex + 1}
-        forwardRef={(ref) => setListOptions(ref, index)}
+        forwardRef={(ref) => setListOptionRefs(ref, index)}
         {...rest}
       >
         <span className="euiComboBoxOption__contentWrapper">
@@ -340,7 +340,7 @@ export class EuiComboBoxOptionsList<T> extends Component<
       delimiter,
       truncationProps,
       listboxAriaLabel,
-      setListOptions,
+      setListOptionRefs,
       ...rest
     } = this.props;
 

From 0e3e7113812b7d52d91c15a1a023653166cf404b Mon Sep 17 00:00:00 2001
From: Lene Gadewoll <lene.gadewoll@elastic.co>
Date: Tue, 1 Jul 2025 10:31:58 +0200
Subject: [PATCH 6/6] chore: update changelog

---
 packages/eui/changelogs/upcoming/8829.md | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/packages/eui/changelogs/upcoming/8829.md b/packages/eui/changelogs/upcoming/8829.md
index 4edd517c07b..7013ae68ccf 100644
--- a/packages/eui/changelogs/upcoming/8829.md
+++ b/packages/eui/changelogs/upcoming/8829.md
@@ -1,3 +1,5 @@
+- Added `setListOptionRefs` prop on `EuiComboBoxList`
+
 **Accessibility**
 
 - Fixed missing screen reader output for `EuiComboBox` with `options` that have custom `id` attributes