From ac94c51551a291856dee1362f4de41bbe90f7bce Mon Sep 17 00:00:00 2001
From: Amanuel Sisay <amanabiy@amazon.de>
Date: Wed, 4 Nov 2026 10:01:56 +0100
Subject: [PATCH 1/5] refactor: Add OptionList support to the shared listbox
 code

Optional additions that OptionList needs and Select and Multiselect don't pass, so their behavior does not change: onEscape is optional in useListbox (without it Escape keeps propagating); PlainList takes scrollStrategy ('menu' by default, 'ancestors' scrolls through the page or a scroll container with the new scrollOptionIntoView); OptionsList statusType is optional with 'finished' as the default; useMenuKeyboard onEscape is optional; the shared item and SelectableItem take hideTopDivider.
---
 .../listbox/__tests__/use-listbox.test.tsx      |  9 +++++++++
 src/internal/components/listbox/parts/item.tsx  |  5 +++++
 .../components/listbox/parts/plain-list.tsx     | 14 +++++++++++---
 .../components/listbox/parts/scroll-to-index.ts | 17 +++++++++++++++++
 src/internal/components/listbox/use-listbox.ts  |  4 ++--
 src/internal/components/options-list/index.tsx  |  7 +++++--
 .../options-list/utils/use-keyboard.ts          |  9 ++++++---
 .../components/selectable-item/index.tsx        |  2 ++
 .../components/selectable-item/interfaces.ts    |  1 +
 .../components/selectable-item/styles.scss      |  6 ++++++
 10 files changed, 64 insertions(+), 10 deletions(-)

diff --git a/src/internal/components/listbox/__tests__/use-listbox.test.tsx b/src/internal/components/listbox/__tests__/use-listbox.test.tsx
index 3d6db3b64d9..e9f939b2776 100644
--- a/src/internal/components/listbox/__tests__/use-listbox.test.tsx
+++ b/src/internal/components/listbox/__tests__/use-listbox.test.tsx
@@ -119,6 +119,15 @@ describe('useListbox', () => {
       expect(onEscape).toHaveBeenCalledTimes(1);
       expect(event.cancelBubble).toBe(true);
     });
+
+    test('is not handled and keeps propagating without onEscape', () => {
+      const { keyDown } = renderListbox({ onEscape: undefined });
+
+      const event = keyDown(KeyCode.escape);
+
+      expect(event.cancelBubble).toBe(false);
+      expect(event.defaultPrevented).toBe(false);
+    });
   });
 
   describe('Home and End', () => {
diff --git a/src/internal/components/listbox/parts/item.tsx b/src/internal/components/listbox/parts/item.tsx
index 8a0f5b4c4f2..354561dadea 100644
--- a/src/internal/components/listbox/parts/item.tsx
+++ b/src/internal/components/listbox/parts/item.tsx
@@ -43,6 +43,8 @@ export interface ItemProps {
   ariaSetsize?: number;
   highlightType?: HighlightType['type'];
   withScrollbar?: boolean;
+  /** Hides the top divider of the first option in lists without a dropdown border above it (OptionList). */
+  hideTopDivider?: boolean;
   sticky?: boolean;
   renderOption?: SelectProps.SelectOptionItemRenderer | MultiselectProps.MultiselectOptionItemRenderer;
   parentProps?: ItemParentProps;
@@ -163,6 +165,7 @@ const Item = (
     ariaSetsize,
     highlightType,
     withScrollbar,
+    hideTopDivider,
     sticky,
     renderOption,
     parentProps,
@@ -311,6 +314,7 @@ const Item = (
         value={option.option.value}
         afterHeader={option.afterHeader}
         withScrollbar={withScrollbar}
+        hideTopDivider={hideTopDivider}
         sticky={sticky}
         {...baseProps}
       >
@@ -352,6 +356,7 @@ const Item = (
       ariaDescribedby={isDisabledWithReason ? descriptionId : ''}
       value={option.option.value}
       withScrollbar={withScrollbar}
+      hideTopDivider={hideTopDivider}
       sticky={sticky}
       {...baseProps}
     >
diff --git a/src/internal/components/listbox/parts/plain-list.tsx b/src/internal/components/listbox/parts/plain-list.tsx
index 5b3c5f432a6..3d20c512289 100644
--- a/src/internal/components/listbox/parts/plain-list.tsx
+++ b/src/internal/components/listbox/parts/plain-list.tsx
@@ -14,7 +14,7 @@ import { GetOptionProps, ListElementProps, ScrollToIndexRef } from '../interface
 import { SelectionType } from '../selection/interfaces';
 import { fallbackItemHeight } from './common';
 import { renderOptions } from './render-options';
-import scrollToIndex from './scroll-to-index';
+import scrollToIndex, { scrollOptionIntoView } from './scroll-to-index';
 
 import styles from '../../../../select/parts/styles.css.js';
 
@@ -31,6 +31,12 @@ export interface ListProps {
   firstOptionSticky?: boolean;
   isMultiSelect?: boolean;
   renderOption?: SelectProps.SelectOptionItemRenderer | MultiselectProps.MultiselectOptionItemRenderer;
+  /**
+   * How the highlighted option is scrolled into view. `menu` (default) scrolls only the list itself.
+   * `ancestors` scrolls through all scrollable ancestors, for a list that is not its own scroll container,
+   * such as in OptionList.
+   */
+  scrollStrategy?: 'menu' | 'ancestors';
 }
 
 const PlainList = (
@@ -47,6 +53,7 @@ const PlainList = (
     firstOptionSticky,
     isMultiSelect,
     renderOption,
+    scrollStrategy = 'menu',
   }: ListProps,
   ref: React.Ref<ScrollToIndexRef>
 ) => {
@@ -75,10 +82,11 @@ const PlainList = (
     () => (index: number) => {
       const isSticky = firstOptionSticky && index === 0;
       if (highlightType.moveFocus && menuRef.current && !isSticky) {
-        scrollToIndex({ index, menuEl: menuRef.current });
+        const scroll = scrollStrategy === 'ancestors' ? scrollOptionIntoView : scrollToIndex;
+        scroll({ index, menuEl: menuRef.current });
       }
     },
-    [firstOptionSticky, highlightType.moveFocus, menuRef]
+    [firstOptionSticky, highlightType.moveFocus, menuRef, scrollStrategy]
   );
 
   const withScrollbar = !!width && width.inner < width.outer;
diff --git a/src/internal/components/listbox/parts/scroll-to-index.ts b/src/internal/components/listbox/parts/scroll-to-index.ts
index 38b5484b15c..620bb786d31 100644
--- a/src/internal/components/listbox/parts/scroll-to-index.ts
+++ b/src/internal/components/listbox/parts/scroll-to-index.ts
@@ -1,5 +1,22 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { scrollElementIntoView } from '../../../utils/scrollable-containers';
+
+/**
+ * Scrolls the option at the given index into view through all its scrollable ancestors.
+ * Used when the list is not its own scroll container, such as in OptionList.
+ */
+export function scrollOptionIntoView({ index, menuEl }: { index: number; menuEl: HTMLElement }) {
+  // -1 means nothing is highlighted. Non-interactive rows such as single-selection group headers also
+  // render with data-mouse-target="-1", so looking it up would scroll to one of them.
+  if (index < 0) {
+    return;
+  }
+  const item = menuEl.querySelector<HTMLElement>(`[data-mouse-target="${index}"]`);
+  if (item) {
+    scrollElementIntoView(item);
+  }
+}
 
 export default function ({ index, menuEl }: { index: number; menuEl: HTMLElement }) {
   const item = menuEl.querySelector<HTMLElement>(`[data-mouse-target="${index}"]`);
diff --git a/src/internal/components/listbox/use-listbox.ts b/src/internal/components/listbox/use-listbox.ts
index 0432185fa0d..198bca46339 100644
--- a/src/internal/components/listbox/use-listbox.ts
+++ b/src/internal/components/listbox/use-listbox.ts
@@ -46,8 +46,8 @@ export interface UseListboxProps {
    * filter input.
    */
   spaceSelects: 'always' | 'keyboard-highlight';
-  /** Called when Escape is pressed. */
-  onEscape: () => void;
+  /** Called when Escape is pressed. When omitted, Escape is not handled and keeps propagating. */
+  onEscape?: () => void;
   /** Group of the option, announced with the highlighted option. */
   getParent: (option: DropdownOption) => undefined | OptionGroup;
   /** Added to the announcement when the highlighted option is selected. */
diff --git a/src/internal/components/options-list/index.tsx b/src/internal/components/options-list/index.tsx
index 400414a960c..1b1b35d801b 100644
--- a/src/internal/components/options-list/index.tsx
+++ b/src/internal/components/options-list/index.tsx
@@ -16,7 +16,10 @@ import styles from './styles.css.js';
 
 export interface OptionsListProps extends BaseComponentProps {
   open?: boolean;
-  statusType: DropdownStatusProps.StatusType;
+  /**
+   * When the list opens with `pending` status, `onLoadMore` fires right away. Defaults to `finished`.
+   */
+  statusType?: DropdownStatusProps.StatusType;
   /**
    * Options list
    */
@@ -60,7 +63,7 @@ const getItemIndex = (containerRef: React.RefObject<HTMLElement>, event: React.M
 const OptionsList = (
   {
     open,
-    statusType,
+    statusType = 'finished',
     children,
     nativeAttributes = {},
     onKeyDown,
diff --git a/src/internal/components/options-list/utils/use-keyboard.ts b/src/internal/components/options-list/utils/use-keyboard.ts
index cda17bb88f8..f5ffb1ae6b1 100644
--- a/src/internal/components/options-list/utils/use-keyboard.ts
+++ b/src/internal/components/options-list/utils/use-keyboard.ts
@@ -13,7 +13,8 @@ interface UseMenuKeyboard {
     selectOption: () => void;
     goHome: () => void;
     goEnd: () => void;
-    onEscape: () => void;
+    /** Escape handler. When omitted, Escape is not handled and keeps propagating. */
+    onEscape?: () => void;
     preventNativeSpace?: boolean;
   }): CancelableEventHandler<BaseKeyDetail>;
 }
@@ -44,8 +45,10 @@ export const useMenuKeyboard: UseMenuKeyboard = ({
         goEnd();
         break;
       case KeyCode.escape:
-        event.stopPropagation();
-        onEscape();
+        if (onEscape) {
+          event.stopPropagation();
+          onEscape();
+        }
         break;
       case KeyCode.enter:
         event.preventDefault();
diff --git a/src/internal/components/selectable-item/index.tsx b/src/internal/components/selectable-item/index.tsx
index 707af463158..5d2ff842399 100644
--- a/src/internal/components/selectable-item/index.tsx
+++ b/src/internal/components/selectable-item/index.tsx
@@ -41,6 +41,7 @@ const SelectableItem = (
     sticky,
     afterHeader,
     withScrollbar,
+    hideTopDivider,
     ...restProps
   }: SelectableItemProps,
   ref: React.Ref<HTMLDivElement>
@@ -65,6 +66,7 @@ const SelectableItem = (
     [styles.sticky]: sticky,
     [styles['after-header']]: !!afterHeader,
     [styles['with-scrollbar']]: withScrollbar,
+    [styles['hide-top-divider']]: hideTopDivider,
     [styles['visual-refresh']]: isVisualRefresh,
   });
 
diff --git a/src/internal/components/selectable-item/interfaces.ts b/src/internal/components/selectable-item/interfaces.ts
index 9fa93d00c47..31ec4f8d56a 100644
--- a/src/internal/components/selectable-item/interfaces.ts
+++ b/src/internal/components/selectable-item/interfaces.ts
@@ -28,6 +28,7 @@ export type SelectableItemProps = BaseComponentProps & {
   sticky?: boolean;
   afterHeader?: boolean;
   withScrollbar?: boolean;
+  hideTopDivider?: boolean;
   ariaSelected?: boolean | never;
   ariaChecked?: boolean | 'mixed' | never;
 };
diff --git a/src/internal/components/selectable-item/styles.scss b/src/internal/components/selectable-item/styles.scss
index 5006969adf7..51ff3d3adc4 100644
--- a/src/internal/components/selectable-item/styles.scss
+++ b/src/internal/components/selectable-item/styles.scss
@@ -210,6 +210,12 @@ $neg-divider-w: calc(-1 * #{$divider-w});
     box-shadow: inset 0 $neg-divider-w 0 0 awsui.$color-border-dropdown-item-default;
   }
 
+  // Used by Option List, where there is no dropdown border above the first item.
+  // Exclude highlighted/selected states to preserve their box-shadow.
+  &.hide-top-divider:not(.highlighted):not(.selected):not(.sticky) {
+    box-shadow: inset 0 $neg-divider-w 0 0 awsui.$color-border-dropdown-item-default;
+  }
+
   &.sticky {
     position: sticky;
     inset-block-start: 0;

From a1696d2db77d78645f91ebbe3b89bf2d97d9fb08 Mon Sep 17 00:00:00 2001
From: Amanuel Sisay <amanabiy@amazon.de>
Date: Wed, 4 Nov 2026 10:01:56 +0100
Subject: [PATCH 2/5] feat: Add OptionList component

OptionList shows selectable options inline, without a dropdown, with single or multi selection, option groups, disabled options with a disabled reason, icons, label tags and tags, custom option rendering (renderOption) and a custom live announcement (renderHighlightedAriaLive).

useOptionList (src/option-list/use-option-list.ts) calls the shared useListbox with embedded: true, which handles focus and blur, and adds the mouse-leave reset and type-ahead. The list renders through the shared PlainList with scrollStrategy 'ancestors'.

Also adds the OptionList test-utils and the option-list i18n namespace.
---
 build-tools/utils/pluralize.js                |   1 +
 .../required-props-for-components.ts          |   1 +
 .../__snapshots__/documenter.test.ts.snap     | 540 ++++++++++++++++++
 .../test-utils-selectors.test.tsx.snap        |   5 +
 .../test-utils-wrappers.test.tsx.snap         |  80 +++
 src/i18n/messages-types.ts                    |   3 +
 src/i18n/messages/all.ar.json                 |   3 +
 src/i18n/messages/all.de.json                 |   3 +
 src/i18n/messages/all.en-GB.json              |   3 +
 src/i18n/messages/all.en.json                 |   3 +
 src/i18n/messages/all.es.json                 |   3 +
 src/i18n/messages/all.fr.json                 |   3 +
 src/i18n/messages/all.id.json                 |   3 +
 src/i18n/messages/all.it.json                 |   3 +
 src/i18n/messages/all.ja.json                 |   3 +
 src/i18n/messages/all.ko.json                 |   3 +
 src/i18n/messages/all.pt-BR.json              |   3 +
 src/i18n/messages/all.th.json                 |   3 +
 src/i18n/messages/all.tr.json                 |   3 +
 src/i18n/messages/all.zh-CN.json              |   3 +
 src/i18n/messages/all.zh-TW.json              |   3 +
 src/option-list/index.tsx                     |  26 +
 src/option-list/interfaces.ts                 | 154 +++++
 src/option-list/internal.tsx                  | 229 ++++++++
 src/option-list/styles.scss                   |  11 +
 src/option-list/test-classes/styles.scss      |   9 +
 src/option-list/use-option-list.ts            | 104 ++++
 src/test-utils/dom/option-list/index.ts       | 132 +++++
 28 files changed, 1340 insertions(+)
 create mode 100644 src/option-list/index.tsx
 create mode 100644 src/option-list/interfaces.ts
 create mode 100644 src/option-list/internal.tsx
 create mode 100644 src/option-list/styles.scss
 create mode 100644 src/option-list/test-classes/styles.scss
 create mode 100644 src/option-list/use-option-list.ts
 create mode 100644 src/test-utils/dom/option-list/index.ts

diff --git a/build-tools/utils/pluralize.js b/build-tools/utils/pluralize.js
index f03df7fa256..c81d1d676c8 100644
--- a/build-tools/utils/pluralize.js
+++ b/build-tools/utils/pluralize.js
@@ -59,6 +59,7 @@ const pluralizationMap = {
   Modal: 'Modals',
   Multiselect: 'Multiselects',
   NavigableGroup: 'NavigableGroups',
+  OptionList: 'OptionLists',
   Pagination: 'Paginations',
   AppLayoutToolbar: 'AppLayoutToolbars',
   PanelLayout: 'PanelLayouts',
diff --git a/src/__tests__/required-props-for-components.ts b/src/__tests__/required-props-for-components.ts
index 37d6772212d..2f37c199453 100644
--- a/src/__tests__/required-props-for-components.ts
+++ b/src/__tests__/required-props-for-components.ts
@@ -8,6 +8,7 @@ const defaultProps: Record<string, Record<string, any>> = {
   table: { columnDefinitions: [] },
   cards: { cardDefinition: {} },
   autosuggest: { options: [], value: '' },
+  'option-list': { options: [], selectionType: 'single' },
   'anchor-navigation': { anchors: [] },
   'code-editor': { i18nStrings },
   wizard: {
diff --git a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
index d1df802eb19..8493604520a 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/documenter.test.ts.snap
@@ -21305,6 +21305,192 @@ need to be direct children of the group:
 }
 `;
 
+exports[`Components definition for option-list matches the snapshot: option-list 1`] = `
+{
+  "dashCaseName": "option-list",
+  "events": [
+    {
+      "cancelable": false,
+      "description": "Called when the user selects or deselects an option.
+The event \`detail\` contains the new \`selectedOptions\`.",
+      "detailInlineType": {
+        "name": "OptionListProps.ChangeDetail",
+        "properties": [
+          {
+            "name": "selectedOptions",
+            "optional": false,
+            "type": "ReadonlyArray<OptionListProps.Option>",
+          },
+        ],
+        "type": "object",
+      },
+      "detailType": "OptionListProps.ChangeDetail",
+      "name": "onChange",
+    },
+  ],
+  "functions": [
+    {
+      "name": "focus",
+      "parameters": [],
+      "returnType": "void",
+    },
+  ],
+  "name": "OptionList",
+  "properties": [
+    {
+      "description": "Adds \`aria-describedby\` to the list.",
+      "name": "ariaDescribedby",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Adds \`aria-label\` to the list. Use this when there is no visible label.",
+      "name": "ariaLabel",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Adds \`aria-labelledby\` to the list. Use this to reference the visible label of the list.",
+      "name": "ariaLabelledby",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "deprecatedTag": "Custom CSS is not supported. For testing and other use cases, use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes).",
+      "description": "Adds the specified classes to the root element of the component.",
+      "name": "className",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "An object containing all the necessary localized strings required by the component.
+* \`selectedAriaLabel\` - Announced with the highlighted option when it is selected.",
+      "i18nTag": true,
+      "inlineType": {
+        "name": "OptionListProps.I18nStrings",
+        "properties": [
+          {
+            "name": "selectedAriaLabel",
+            "optional": true,
+            "type": "string",
+          },
+        ],
+        "type": "object",
+      },
+      "name": "i18nStrings",
+      "optional": true,
+      "type": "OptionListProps.I18nStrings",
+    },
+    {
+      "deprecatedTag": "The usage of the \`id\` attribute is reserved for internal use cases. For testing and other use cases,
+use [data attributes](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes). If you must
+use the \`id\` attribute, consider setting it on a parent element instead.",
+      "description": "Adds the specified ID to the root element of the component.",
+      "name": "id",
+      "optional": true,
+      "type": "string",
+    },
+    {
+      "description": "Specifies an array of options that are displayed as a list.
+You can group options into one level of option groups.
+
+#### Option
+- \`value\` (string) - The returned value of the option when selected. Must be unique.
+- \`label\` (string) - (Optional) Option text displayed to the user.
+- \`lang\` (string) - (Optional) The language of the option, provided as a BCP 47 language tag.
+- \`description\` (string) - (Optional) Further information about the option that appears below the label.
+- \`disabled\` (boolean) - (Optional) Determines whether the option is disabled. Users can't select or deselect a disabled option.
+- \`disabledReason\` (ReactNode) - (Optional) Displays a tooltip near the item when disabled. Use to provide additional context.
+- \`labelTag\` (string) - (Optional) A label tag that provides additional guidance, shown next to the label.
+- \`tags\` [string[]] - (Optional) A list of tags giving further guidance about the option.
+- \`icon\` (ReactNode) - (Optional) An icon displayed in the option, such as an [icon component](/components/icon/).
+
+#### OptionGroup
+- \`value\` (string) - Identifies the option group. Must be unique among the groups.
+- \`label\` (string) - Option group text displayed to the user.
+- \`disabled\` (boolean) - (Optional) Determines whether the option group is disabled. Disables every option in the group.
+- \`options\` (Option[]) - The options in the group.
+
+Options are the selection target. Do not render interactive elements such as buttons or links inside them.",
+      "name": "options",
+      "optional": false,
+      "type": "OptionListProps.Options",
+    },
+    {
+      "description": "Overrides the element that is announced to screen readers
+when the highlighted option changes. By default, this announces
+the option's name and properties, and its selected state if
+the \`selectedAriaLabel\` property is defined.
+The highlighted option is provided, and its group (if groups
+are used and it differs from the group of the previously highlighted option).
+In multi selection, when a group header is highlighted, the group is provided as the option.
+
+For more information, see the
+[accessibility guidelines](/components/select/?tabId=usage#accessibility-guidelines).",
+      "inlineType": {
+        "name": "OptionListProps.ContainingOptionAndGroupString",
+        "parameters": [
+          {
+            "name": "option",
+            "type": "OptionListProps.Option | OptionListProps.OptionGroup",
+          },
+          {
+            "name": "group",
+            "type": "OptionListProps.OptionGroup",
+          },
+        ],
+        "returnType": "string",
+        "type": "function",
+      },
+      "name": "renderHighlightedAriaLive",
+      "optional": true,
+      "type": "OptionListProps.ContainingOptionAndGroupString",
+    },
+    {
+      "description": "Specifies a render function to render custom options.",
+      "inlineType": {
+        "name": "OptionListProps.OptionItemRenderer",
+        "parameters": [
+          {
+            "name": "props",
+            "type": "{ item: OptionListProps.Item; }",
+          },
+        ],
+        "returnType": "React.ReactNode",
+        "type": "function",
+      },
+      "name": "renderOption",
+      "optional": true,
+      "type": "OptionListProps.OptionItemRenderer",
+    },
+    {
+      "description": "The selected options. Options are matched by \`value\`. In single selection, only the first option of the array is used.
+If you don't provide this property, the component manages its selection internally.",
+      "name": "selectedOptions",
+      "optional": true,
+      "type": "ReadonlyArray<OptionListProps.Option>",
+    },
+    {
+      "description": "Specifies whether the user can select one option (\`single\`) or several (\`multi\`).
+Multi selection shows a checkbox next to each option.",
+      "inlineType": {
+        "name": "OptionListProps.SelectionType",
+        "type": "union",
+        "values": [
+          "single",
+          "multi",
+        ],
+      },
+      "name": "selectionType",
+      "optional": false,
+      "type": "string",
+    },
+  ],
+  "regions": [],
+  "releaseStatus": "stable",
+}
+`;
+
 exports[`Components definition for pagination matches the snapshot: pagination 1`] = `
 {
   "dashCaseName": "pagination",
@@ -45021,6 +45207,204 @@ wrapper.selectOptionByValue('option_1');
       ],
       "name": "NavigableGroupWrapper",
     },
+    {
+      "methods": [
+        {
+          "description": "Returns an option group header for a given value.",
+          "name": "findGroupHeaderByValue",
+          "parameters": [
+            {
+              "description": "The \`value\` of the option group.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "value",
+              "typeName": "string",
+            },
+          ],
+          "returnType": {
+            "isNullable": true,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns all option group headers.",
+          "name": "findGroupHeaders",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "Array",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns the highlighted option. Group headers are not included.",
+          "name": "findHighlightedOption",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns an option for a given index. Group headers are not counted.",
+          "name": "findOptionByIndex",
+          "parameters": [
+            {
+              "description": "1-based index of the option to return.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "index",
+              "typeName": "number",
+            },
+          ],
+          "returnType": {
+            "isNullable": true,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns an option for a given value.",
+          "name": "findOptionByValue",
+          "parameters": [
+            {
+              "description": "The \`value\` of the option.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "value",
+              "typeName": "string",
+            },
+          ],
+          "returnType": {
+            "isNullable": true,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns all options. Group headers are not included.",
+          "name": "findOptions",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "Array",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns all selected options. Group headers are not included.",
+          "name": "findSelectedOptions",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "Array",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+      ],
+      "name": "OptionListWrapper",
+    },
+    {
+      "methods": [
+        {
+          "description": "Returns the option description.",
+          "name": "findDescription",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "ElementWrapper",
+            "typeArguments": [
+              {
+                "name": "HTMLElement",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns the option label.",
+          "name": "findLabel",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "ElementWrapper",
+            "typeArguments": [
+              {
+                "name": "HTMLElement",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns the option label tag.",
+          "name": "findLabelTag",
+          "parameters": [],
+          "returnType": {
+            "isNullable": true,
+            "name": "ElementWrapper",
+            "typeArguments": [
+              {
+                "name": "HTMLElement",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns the option tags.",
+          "name": "findTags",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "Array",
+            "typeArguments": [
+              {
+                "name": "ElementWrapper<HTMLElement>",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns \`true\` if the option is disabled.",
+          "name": "isDisabled",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "boolean",
+          },
+        },
+        {
+          "description": "Returns \`true\` if the option is highlighted.",
+          "name": "isHighlighted",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "boolean",
+          },
+        },
+        {
+          "description": "Returns \`true\` if the option is selected. A group header in multi selection is selected when all its options are selected.",
+          "name": "isSelected",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "boolean",
+          },
+        },
+      ],
+      "name": "OptionListOptionWrapper",
+    },
     {
       "methods": [
         {
@@ -56055,6 +56439,162 @@ The dismiss button is only rendered when the \`dismissible\` property is set to
       ],
       "name": "NavigableGroupWrapper",
     },
+    {
+      "methods": [
+        {
+          "description": "Returns an option group header for a given value.",
+          "name": "findGroupHeaderByValue",
+          "parameters": [
+            {
+              "description": "The \`value\` of the option group.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "value",
+              "typeName": "string",
+            },
+          ],
+          "returnType": {
+            "isNullable": false,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns all option group headers.",
+          "name": "findGroupHeaders",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "MultiElementWrapper",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns the highlighted option. Group headers are not included.",
+          "name": "findHighlightedOption",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns an option for a given index. Group headers are not counted.",
+          "name": "findOptionByIndex",
+          "parameters": [
+            {
+              "description": "1-based index of the option to return.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "index",
+              "typeName": "number",
+            },
+          ],
+          "returnType": {
+            "isNullable": false,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns an option for a given value.",
+          "name": "findOptionByValue",
+          "parameters": [
+            {
+              "description": "The \`value\` of the option.",
+              "flags": {
+                "isOptional": false,
+              },
+              "name": "value",
+              "typeName": "string",
+            },
+          ],
+          "returnType": {
+            "isNullable": false,
+            "name": "OptionListOptionWrapper",
+          },
+        },
+        {
+          "description": "Returns all options. Group headers are not included.",
+          "name": "findOptions",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "MultiElementWrapper",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+        {
+          "description": "Returns all selected options. Group headers are not included.",
+          "name": "findSelectedOptions",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "MultiElementWrapper",
+            "typeArguments": [
+              {
+                "name": "OptionListOptionWrapper",
+              },
+            ],
+          },
+        },
+      ],
+      "name": "OptionListWrapper",
+    },
+    {
+      "methods": [
+        {
+          "description": "Returns the option description.",
+          "name": "findDescription",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "ElementWrapper",
+          },
+        },
+        {
+          "description": "Returns the option label.",
+          "name": "findLabel",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "ElementWrapper",
+          },
+        },
+        {
+          "description": "Returns the option label tag.",
+          "name": "findLabelTag",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "ElementWrapper",
+          },
+        },
+        {
+          "description": "Returns the option tags.",
+          "name": "findTags",
+          "parameters": [],
+          "returnType": {
+            "isNullable": false,
+            "name": "MultiElementWrapper",
+            "typeArguments": [
+              {
+                "name": "ElementWrapper",
+              },
+            ],
+          },
+        },
+      ],
+      "name": "OptionListOptionWrapper",
+    },
     {
       "methods": [
         {
diff --git a/src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap b/src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap
index cccb90c75cb..7a132d00a3c 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/test-utils-selectors.test.tsx.snap
@@ -517,6 +517,11 @@ exports[`test-utils selectors 1`] = `
   "navigable-group": [
     "awsui_root_efqlv",
   ],
+  "option-list": [
+    "awsui_group-header_1kbcw",
+    "awsui_option_1kbcw",
+    "awsui_root_1kbcw",
+  ],
   "pagination": [
     "awsui_arrow_fvjdu",
     "awsui_button-current_fvjdu",
diff --git a/src/__tests__/snapshot-tests/__snapshots__/test-utils-wrappers.test.tsx.snap b/src/__tests__/snapshot-tests/__snapshots__/test-utils-wrappers.test.tsx.snap
index 0ae69c9b241..5d123e012f3 100644
--- a/src/__tests__/snapshot-tests/__snapshots__/test-utils-wrappers.test.tsx.snap
+++ b/src/__tests__/snapshot-tests/__snapshots__/test-utils-wrappers.test.tsx.snap
@@ -67,6 +67,7 @@ import MixedLineBarChartWrapper from './mixed-line-bar-chart';
 import ModalWrapper from './modal';
 import MultiselectWrapper from './multiselect';
 import NavigableGroupWrapper from './navigable-group';
+import OptionListWrapper from './option-list';
 import PaginationWrapper from './pagination';
 import PanelLayoutWrapper from './panel-layout';
 import PieChartWrapper from './pie-chart';
@@ -171,6 +172,7 @@ export { MixedLineBarChartWrapper };
 export { ModalWrapper };
 export { MultiselectWrapper };
 export { NavigableGroupWrapper };
+export { OptionListWrapper };
 export { PaginationWrapper };
 export { PanelLayoutWrapper };
 export { PieChartWrapper };
@@ -1843,6 +1845,34 @@ findAllNavigableGroups(selector?: string): Array<NavigableGroupWrapper>;
  * @returns {NavigableGroupWrapper | null}
  */
 findClosestNavigableGroup(): NavigableGroupWrapper | null;
+/**
+ * Returns the wrapper of the first OptionList that matches the specified CSS selector.
+ * If no CSS selector is specified, returns the wrapper of the first OptionList.
+ * If no matching OptionList is found, returns \`null\`.
+ *
+ * @param {string} [selector] CSS Selector
+ * @returns {OptionListWrapper | null}
+ */
+findOptionList(selector?: string): OptionListWrapper | null;
+
+/**
+ * Returns an array of OptionList wrapper that matches the specified CSS selector.
+ * If no CSS selector is specified, returns all of the OptionLists inside the current wrapper.
+ * If no matching OptionList is found, returns an empty array.
+ *
+ * @param {string} [selector] CSS Selector
+ * @returns {Array<OptionListWrapper>}
+ */
+findAllOptionLists(selector?: string): Array<OptionListWrapper>;
+
+/**
+ * Returns the wrapper of the closest parent OptionList for the current element,
+ * or the element itself if it is an instance of OptionList.
+ * If no OptionList is found, returns \`null\`.
+ *
+ * @returns {OptionListWrapper | null}
+ */
+findClosestOptionList(): OptionListWrapper | null;
 /**
  * Returns the wrapper of the first Pagination that matches the specified CSS selector.
  * If no CSS selector is specified, returns the wrapper of the first Pagination.
@@ -3833,6 +3863,19 @@ ElementWrapper.prototype.findNavigableGroup = function(selector) {
 ElementWrapper.prototype.findAllNavigableGroups = function(selector) {
   return this.findAllComponents(NavigableGroupWrapper, selector);
 };
+ElementWrapper.prototype.findOptionList = function(selector) {
+  let rootSelector = \`.\${OptionListWrapper.rootSelector}\`;
+  if("legacyRootSelector" in OptionListWrapper && OptionListWrapper.legacyRootSelector){
+    rootSelector = \`:is(.\${OptionListWrapper.rootSelector}, .\${OptionListWrapper.legacyRootSelector})\`;
+  }
+  // casting to 'any' is needed to avoid this issue with generics
+  // https://github.com/microsoft/TypeScript/issues/29132
+  return (this as any).findComponent(selector ? appendSelector(selector, rootSelector) : rootSelector, OptionListWrapper);
+};
+
+ElementWrapper.prototype.findAllOptionLists = function(selector) {
+  return this.findAllComponents(OptionListWrapper, selector);
+};
 ElementWrapper.prototype.findPagination = function(selector) {
   let rootSelector = \`.\${PaginationWrapper.rootSelector}\`;
   if("legacyRootSelector" in PaginationWrapper && PaginationWrapper.legacyRootSelector){
@@ -4696,6 +4739,11 @@ ElementWrapper.prototype.findClosestNavigableGroup = function() {
   // https://github.com/microsoft/TypeScript/issues/29132
   return (this as any).findClosestComponent(NavigableGroupWrapper);
 };
+ElementWrapper.prototype.findClosestOptionList = function() {
+  // casting to 'any' is needed to avoid this issue with generics
+  // https://github.com/microsoft/TypeScript/issues/29132
+  return (this as any).findClosestComponent(OptionListWrapper);
+};
 ElementWrapper.prototype.findClosestPagination = function() {
   // casting to 'any' is needed to avoid this issue with generics
   // https://github.com/microsoft/TypeScript/issues/29132
@@ -4993,6 +5041,7 @@ import MixedLineBarChartWrapper from './mixed-line-bar-chart';
 import ModalWrapper from './modal';
 import MultiselectWrapper from './multiselect';
 import NavigableGroupWrapper from './navigable-group';
+import OptionListWrapper from './option-list';
 import PaginationWrapper from './pagination';
 import PanelLayoutWrapper from './panel-layout';
 import PieChartWrapper from './pie-chart';
@@ -5097,6 +5146,7 @@ export { MixedLineBarChartWrapper };
 export { ModalWrapper };
 export { MultiselectWrapper };
 export { NavigableGroupWrapper };
+export { OptionListWrapper };
 export { PaginationWrapper };
 export { PanelLayoutWrapper };
 export { PieChartWrapper };
@@ -6131,6 +6181,23 @@ findNavigableGroup(selector?: string): NavigableGroupWrapper;
  * @returns {MultiElementWrapper<NavigableGroupWrapper>}
  */
 findAllNavigableGroups(selector?: string): MultiElementWrapper<NavigableGroupWrapper>;
+/**
+ * Returns a wrapper that matches the OptionLists with the specified CSS selector.
+ * If no CSS selector is specified, returns a wrapper that matches OptionLists.
+ *
+ * @param {string} [selector] CSS Selector
+ * @returns {OptionListWrapper}
+ */
+findOptionList(selector?: string): OptionListWrapper;
+
+/**
+ * Returns a multi-element wrapper that matches OptionLists with the specified CSS selector.
+ * If no CSS selector is specified, returns a multi-element wrapper that matches OptionLists.
+ *
+ * @param {string} [selector] CSS Selector
+ * @returns {MultiElementWrapper<OptionListWrapper>}
+ */
+findAllOptionLists(selector?: string): MultiElementWrapper<OptionListWrapper>;
 /**
  * Returns a wrapper that matches the Paginations with the specified CSS selector.
  * If no CSS selector is specified, returns a wrapper that matches Paginations.
@@ -7637,6 +7704,19 @@ ElementWrapper.prototype.findNavigableGroup = function(selector) {
 ElementWrapper.prototype.findAllNavigableGroups = function(selector) {
   return this.findAllComponents(NavigableGroupWrapper, selector);
 };
+ElementWrapper.prototype.findOptionList = function(selector) {
+  let rootSelector = \`.\${OptionListWrapper.rootSelector}\`;
+  if("legacyRootSelector" in OptionListWrapper && OptionListWrapper.legacyRootSelector){
+    rootSelector = \`:is(.\${OptionListWrapper.rootSelector}, .\${OptionListWrapper.legacyRootSelector})\`;
+  }
+  // casting to 'any' is needed to avoid this issue with generics
+  // https://github.com/microsoft/TypeScript/issues/29132
+  return (this as any).findComponent(selector ? appendSelector(selector, rootSelector) : rootSelector, OptionListWrapper);
+};
+
+ElementWrapper.prototype.findAllOptionLists = function(selector) {
+  return this.findAllComponents(OptionListWrapper, selector);
+};
 ElementWrapper.prototype.findPagination = function(selector) {
   let rootSelector = \`.\${PaginationWrapper.rootSelector}\`;
   if("legacyRootSelector" in PaginationWrapper && PaginationWrapper.legacyRootSelector){
diff --git a/src/i18n/messages-types.ts b/src/i18n/messages-types.ts
index f2e87738126..46cfaeb5e6a 100644
--- a/src/i18n/messages-types.ts
+++ b/src/i18n/messages-types.ts
@@ -379,6 +379,9 @@ export interface I18nFormatArgTypes {
     }
     "i18nStrings.selectAllText": never;
   }
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": never;
+  }
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": never;
     "ariaLabels.nextPageLabel": never;
diff --git a/src/i18n/messages/all.ar.json b/src/i18n/messages/all.ar.json
index a97ca523c51..dfcdab61ae3 100644
--- a/src/i18n/messages/all.ar.json
+++ b/src/i18n/messages/all.ar.json
@@ -255,6 +255,9 @@
     "deselectAriaLabel": "إزالة {option__label}",
     "i18nStrings.selectAllText": "حدد الكل"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "مُحدَّد"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "الانتقال إلى الصفحة",
     "ariaLabels.nextPageLabel": "الصفحة التالية",
diff --git a/src/i18n/messages/all.de.json b/src/i18n/messages/all.de.json
index 5541eed328a..e0e81e214ba 100644
--- a/src/i18n/messages/all.de.json
+++ b/src/i18n/messages/all.de.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "{option__label} entfernen",
     "i18nStrings.selectAllText": "Alles auswählen"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Ausgewählt"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Zur Seite springen",
     "ariaLabels.nextPageLabel": "Nächste Seite",
diff --git a/src/i18n/messages/all.en-GB.json b/src/i18n/messages/all.en-GB.json
index 2610e463819..720d0ef49b4 100644
--- a/src/i18n/messages/all.en-GB.json
+++ b/src/i18n/messages/all.en-GB.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Remove {option__label}",
     "i18nStrings.selectAllText": "Select all"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Selected"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Jump to page",
     "ariaLabels.nextPageLabel": "Next page",
diff --git a/src/i18n/messages/all.en.json b/src/i18n/messages/all.en.json
index 7b4bb5ca9b7..c32103069f8 100644
--- a/src/i18n/messages/all.en.json
+++ b/src/i18n/messages/all.en.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Remove {option__label}",
     "i18nStrings.selectAllText": "Select all"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Selected"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Jump to page",
     "ariaLabels.nextPageLabel": "Next page",
diff --git a/src/i18n/messages/all.es.json b/src/i18n/messages/all.es.json
index 37404a5e445..e794344e043 100644
--- a/src/i18n/messages/all.es.json
+++ b/src/i18n/messages/all.es.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Eliminar {option__label}",
     "i18nStrings.selectAllText": "Seleccionar todo"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Seleccionado"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Ir a la página",
     "ariaLabels.nextPageLabel": "Página siguiente",
diff --git a/src/i18n/messages/all.fr.json b/src/i18n/messages/all.fr.json
index 8063516b962..62d0dbb6dff 100644
--- a/src/i18n/messages/all.fr.json
+++ b/src/i18n/messages/all.fr.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Supprimer {option__label}",
     "i18nStrings.selectAllText": "Tout sélectionner"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Sélectionné"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Aller à la page",
     "ariaLabels.nextPageLabel": "Page suivante",
diff --git a/src/i18n/messages/all.id.json b/src/i18n/messages/all.id.json
index 5257c04142b..30bfbcff9b5 100644
--- a/src/i18n/messages/all.id.json
+++ b/src/i18n/messages/all.id.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Hapus {option__label}",
     "i18nStrings.selectAllText": "Pilih semua"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Dipilih"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Langsung ke halaman",
     "ariaLabels.nextPageLabel": "Halaman berikutnya",
diff --git a/src/i18n/messages/all.it.json b/src/i18n/messages/all.it.json
index 2f451754556..9fbda32d29d 100644
--- a/src/i18n/messages/all.it.json
+++ b/src/i18n/messages/all.it.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Rimuovi {option__label}",
     "i18nStrings.selectAllText": "Seleziona tutto"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Selezionato"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Vai alla pagina",
     "ariaLabels.nextPageLabel": "Pagina successiva",
diff --git a/src/i18n/messages/all.ja.json b/src/i18n/messages/all.ja.json
index 02e532b373f..d640b48bde3 100644
--- a/src/i18n/messages/all.ja.json
+++ b/src/i18n/messages/all.ja.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "{option__label} を削除",
     "i18nStrings.selectAllText": "すべて選択"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "選択済み"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "ページに移動",
     "ariaLabels.nextPageLabel": "次のページ",
diff --git a/src/i18n/messages/all.ko.json b/src/i18n/messages/all.ko.json
index 6befcd4d0d3..287896856f1 100644
--- a/src/i18n/messages/all.ko.json
+++ b/src/i18n/messages/all.ko.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "{option__label} 제거",
     "i18nStrings.selectAllText": "모두 선택"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "선택됨"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "페이지로 이동",
     "ariaLabels.nextPageLabel": "다음 페이지",
diff --git a/src/i18n/messages/all.pt-BR.json b/src/i18n/messages/all.pt-BR.json
index 0b1255e618b..0f2b9ba76b0 100644
--- a/src/i18n/messages/all.pt-BR.json
+++ b/src/i18n/messages/all.pt-BR.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "Remover {option__label}",
     "i18nStrings.selectAllText": "Selecionar tudo"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Selecionado"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Ir para a página",
     "ariaLabels.nextPageLabel": "Próxima página",
diff --git a/src/i18n/messages/all.th.json b/src/i18n/messages/all.th.json
index f1a11920b08..eaae619910b 100644
--- a/src/i18n/messages/all.th.json
+++ b/src/i18n/messages/all.th.json
@@ -160,6 +160,9 @@
   "multiselect": {
     "deselectAriaLabel": "ลบ {option__label}"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "เลือกไว้"
+  },
   "pagination": {
     "ariaLabels.nextPageLabel": "หน้าถัดไป",
     "ariaLabels.pageLabel": "หน้า {pageNumber} จากทุกหน้า",
diff --git a/src/i18n/messages/all.tr.json b/src/i18n/messages/all.tr.json
index 22107ad6d5e..7c088f10343 100644
--- a/src/i18n/messages/all.tr.json
+++ b/src/i18n/messages/all.tr.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "{option__label} ögesini kaldır",
     "i18nStrings.selectAllText": "Tümünü seç"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "Seçili"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Sayfaya atla",
     "ariaLabels.nextPageLabel": "Sonraki sayfa",
diff --git a/src/i18n/messages/all.zh-CN.json b/src/i18n/messages/all.zh-CN.json
index 53e89882323..22863cfb15a 100644
--- a/src/i18n/messages/all.zh-CN.json
+++ b/src/i18n/messages/all.zh-CN.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "删除 {option__label}",
     "i18nStrings.selectAllText": "选择全部"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "已选定"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "跳转到页面",
     "ariaLabels.nextPageLabel": "下一页",
diff --git a/src/i18n/messages/all.zh-TW.json b/src/i18n/messages/all.zh-TW.json
index daa0cf33cc3..741e4a57813 100644
--- a/src/i18n/messages/all.zh-TW.json
+++ b/src/i18n/messages/all.zh-TW.json
@@ -280,6 +280,9 @@
     "deselectAriaLabel": "移除 {option__label}",
     "i18nStrings.selectAllText": "選取全部"
   },
+  "option-list": {
+    "i18nStrings.selectedAriaLabel": "已選取"
+  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "跳到頁面",
     "ariaLabels.nextPageLabel": "下一頁",
diff --git a/src/option-list/index.tsx b/src/option-list/index.tsx
new file mode 100644
index 00000000000..7c37dde95a0
--- /dev/null
+++ b/src/option-list/index.tsx
@@ -0,0 +1,26 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+'use client';
+import React from 'react';
+
+import useBaseComponent from '../internal/hooks/use-base-component';
+import { applyDisplayName } from '../internal/utils/apply-display-name';
+import { getExternalProps } from '../internal/utils/external-props';
+import { OptionListProps } from './interfaces';
+import InternalOptionList from './internal';
+
+export { OptionListProps };
+
+const OptionList = React.forwardRef((props: OptionListProps, ref: React.Ref<OptionListProps.Ref>) => {
+  const baseComponentProps = useBaseComponent('OptionList', {
+    props: { selectionType: props.selectionType },
+    metadata: {
+      optionsCount: props.options.length,
+    },
+  });
+  const externalProps = getExternalProps(props);
+  return <InternalOptionList {...externalProps} {...baseComponentProps} ref={ref} />;
+});
+
+applyDisplayName(OptionList, 'OptionList');
+export default OptionList;
diff --git a/src/option-list/interfaces.ts b/src/option-list/interfaces.ts
new file mode 100644
index 00000000000..864f0464040
--- /dev/null
+++ b/src/option-list/interfaces.ts
@@ -0,0 +1,154 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import { BaseComponentProps } from '../types/base-component';
+import { NonCancelableEventHandler } from '../types/events';
+
+export interface OptionListProps extends BaseComponentProps {
+  /**
+   * Specifies an array of options that are displayed as a list.
+   * You can group options into one level of option groups.
+   *
+   * #### Option
+   * - `value` (string) - The returned value of the option when selected. Must be unique.
+   * - `label` (string) - (Optional) Option text displayed to the user.
+   * - `lang` (string) - (Optional) The language of the option, provided as a BCP 47 language tag.
+   * - `description` (string) - (Optional) Further information about the option that appears below the label.
+   * - `disabled` (boolean) - (Optional) Determines whether the option is disabled. Users can't select or deselect a disabled option.
+   * - `disabledReason` (ReactNode) - (Optional) Displays a tooltip near the item when disabled. Use to provide additional context.
+   * - `labelTag` (string) - (Optional) A label tag that provides additional guidance, shown next to the label.
+   * - `tags` [string[]] - (Optional) A list of tags giving further guidance about the option.
+   * - `icon` (ReactNode) - (Optional) An icon displayed in the option, such as an [icon component](/components/icon/).
+   *
+   * #### OptionGroup
+   * - `value` (string) - Identifies the option group. Must be unique among the groups.
+   * - `label` (string) - Option group text displayed to the user.
+   * - `disabled` (boolean) - (Optional) Determines whether the option group is disabled. Disables every option in the group.
+   * - `options` (Option[]) - The options in the group.
+   *
+   * Options are the selection target. Do not render interactive elements such as buttons or links inside them.
+   */
+  options: OptionListProps.Options;
+
+  /**
+   * Specifies whether the user can select one option (`single`) or several (`multi`).
+   * Multi selection shows a checkbox next to each option.
+   */
+  selectionType: OptionListProps.SelectionType;
+
+  /**
+   * The selected options. Options are matched by `value`. In single selection, only the first option of the array is used.
+   * If you don't provide this property, the component manages its selection internally.
+   */
+  selectedOptions?: ReadonlyArray<OptionListProps.Option>;
+
+  /**
+   * Called when the user selects or deselects an option.
+   * The event `detail` contains the new `selectedOptions`.
+   */
+  onChange?: NonCancelableEventHandler<OptionListProps.ChangeDetail>;
+
+  /**
+   * Adds `aria-label` to the list. Use this when there is no visible label.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Adds `aria-labelledby` to the list. Use this to reference the visible label of the list.
+   */
+  ariaLabelledby?: string;
+
+  /**
+   * Adds `aria-describedby` to the list.
+   */
+  ariaDescribedby?: string;
+
+  /**
+   * Specifies a render function to render custom options.
+   */
+  renderOption?: OptionListProps.OptionItemRenderer;
+
+  /**
+   * Overrides the element that is announced to screen readers
+   * when the highlighted option changes. By default, this announces
+   * the option's name and properties, and its selected state if
+   * the `selectedAriaLabel` property is defined.
+   * The highlighted option is provided, and its group (if groups
+   * are used and it differs from the group of the previously highlighted option).
+   * In multi selection, when a group header is highlighted, the group is provided as the option.
+   *
+   * For more information, see the
+   * [accessibility guidelines](/components/select/?tabId=usage#accessibility-guidelines).
+   */
+  renderHighlightedAriaLive?: OptionListProps.ContainingOptionAndGroupString;
+
+  /**
+   * An object containing all the necessary localized strings required by the component.
+   * * `selectedAriaLabel` - Announced with the highlighted option when it is selected.
+   * @i18n
+   */
+  i18nStrings?: OptionListProps.I18nStrings;
+}
+
+export namespace OptionListProps {
+  export type SelectionType = 'single' | 'multi';
+
+  export interface Option {
+    value: string;
+    label?: string;
+    lang?: string;
+    description?: string;
+    disabled?: boolean;
+    disabledReason?: React.ReactNode;
+    labelTag?: string;
+    tags?: ReadonlyArray<string>;
+    icon?: React.ReactNode;
+  }
+
+  export interface OptionGroup extends Option {
+    options: ReadonlyArray<Option>;
+  }
+
+  export type Options = ReadonlyArray<Option | OptionGroup>;
+
+  export interface OptionItem {
+    type: 'item';
+    index: number;
+    option: Option;
+    selected: boolean;
+    highlighted: boolean;
+    disabled: boolean;
+    parent: OptionGroupItem | null;
+  }
+
+  export interface OptionGroupItem {
+    type: 'group';
+    index: number;
+    option: OptionGroup;
+    disabled: boolean;
+    selected?: boolean;
+    indeterminate?: boolean;
+    highlighted?: boolean;
+  }
+
+  export type Item = OptionItem | OptionGroupItem;
+
+  export type OptionItemRenderer = (props: { item: Item }) => React.ReactNode | null;
+
+  export interface ContainingOptionAndGroupString {
+    (option: Option | OptionGroup, group?: OptionGroup): string;
+  }
+
+  export interface ChangeDetail {
+    selectedOptions: ReadonlyArray<Option>;
+  }
+
+  export interface I18nStrings {
+    selectedAriaLabel?: string;
+  }
+
+  export interface Ref {
+    focus(): void;
+  }
+}
diff --git a/src/option-list/internal.tsx b/src/option-list/internal.tsx
new file mode 100644
index 00000000000..a04b1de5806
--- /dev/null
+++ b/src/option-list/internal.tsx
@@ -0,0 +1,229 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useCallback, useMemo } from 'react';
+import clsx from 'clsx';
+
+import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
+
+import { useInternalI18n } from '../i18n/context';
+import { getBaseProps } from '../internal/base-component';
+import { ItemProps } from '../internal/components/listbox/parts/item';
+import PlainList from '../internal/components/listbox/parts/plain-list';
+import { multiSelection } from '../internal/components/listbox/selection/multi-selection';
+import { singleSelection } from '../internal/components/listbox/selection/single-selection';
+import { checkOptionValueField } from '../internal/components/listbox/utils/check-option-value-field';
+import { isGroup } from '../internal/components/option/utils/filter-options';
+import { prepareOptions } from '../internal/components/option/utils/prepare-options';
+import { fireNonCancelableEvent } from '../internal/events';
+import useForwardFocus from '../internal/hooks/forward-focus';
+import { InternalBaseComponentProps } from '../internal/hooks/use-base-component';
+import { useControllable } from '../internal/hooks/use-controllable';
+import { OptionDefinition, OptionGroup } from '../types/option';
+import { OptionListProps } from './interfaces';
+import { useOptionList } from './use-option-list';
+
+import optionStyles from '../internal/components/option/styles.css.js';
+import styles from './styles.css.js';
+import testClasses from './test-classes/styles.css.js';
+
+type InternalOptionListProps = OptionListProps & InternalBaseComponentProps;
+type InternalOption = OptionDefinition | OptionGroup;
+
+// The items the listbox passes to `renderOption`, before they are mapped back to the consumer's options.
+type ListboxRenderItem = Parameters<NonNullable<ItemProps['renderOption']>>[0]['item'];
+type ListboxGroupItem = Extract<ListboxRenderItem, { type: 'group' }>;
+type ListboxRenderOption = (props: { item: ListboxRenderItem }) => React.ReactNode;
+
+const EMPTY_SELECTION: ReadonlyArray<OptionListProps.Option> = [];
+
+const isOptionGroup = (
+  option: OptionListProps.Option | OptionListProps.OptionGroup
+): option is OptionListProps.OptionGroup => isGroup(option as InternalOption);
+
+/**
+ * Converts the public options to the options the shared list renders: the `icon` slot becomes the custom icon of
+ * the shared option renderer. `originals` maps each converted option back to the consumer's object, so events and
+ * `renderOption` receive the consumer's options.
+ */
+function toInternalOptions(options: OptionListProps.Options) {
+  const originals = new Map<OptionDefinition, OptionListProps.Option>();
+  const originalGroups = new Map<OptionGroup, OptionListProps.OptionGroup>();
+  // Options and group headers.
+  const convert = ({ icon, ...option }: OptionListProps.Option): OptionDefinition => {
+    // The shared option renders a custom icon as is, so wrap it in the same class as the built-in icon of Select and
+    // Multiselect options, for the same spacing and alignment.
+    const internal: OptionDefinition & { __customIcon?: React.ReactNode } = {
+      ...option,
+      __customIcon: icon && <span className={optionStyles.icon}>{icon}</span>,
+    };
+    return internal;
+  };
+  const internalOptions = options.map<InternalOption>(option => {
+    if (!isOptionGroup(option)) {
+      const internal = convert(option);
+      originals.set(internal, option);
+      return internal;
+    }
+    const children = option.options.map(child => {
+      const internal = convert(child);
+      originals.set(internal, child);
+      return internal;
+    });
+    const group: OptionGroup = { ...convert(option), options: children };
+    originalGroups.set(group, option);
+    return group;
+  });
+  return { internalOptions, originals, originalGroups };
+}
+
+const InternalOptionList = React.forwardRef(
+  (
+    {
+      options,
+      selectionType,
+      selectedOptions: controlledSelectedOptions,
+      onChange,
+      ariaLabel,
+      ariaLabelledby,
+      ariaDescribedby,
+      renderOption,
+      renderHighlightedAriaLive,
+      i18nStrings,
+      __internalRootRef,
+      ...restProps
+    }: InternalOptionListProps,
+    ref: React.Ref<OptionListProps.Ref>
+  ) => {
+    const baseProps = getBaseProps(restProps);
+    const i18n = useInternalI18n('option-list');
+
+    const { listOptions, parentMap, originals, originalGroups, hasDuplicateValues, hasDuplicateGroupValues } =
+      useMemo(() => {
+        const { internalOptions, originals, originalGroups } = toInternalOptions(options);
+        // Also sets the test indexes that test-utils use to find an option by its position.
+        const { flatOptions, parentMap } = prepareOptions(internalOptions, 'none', '');
+        const values = flatOptions.filter(option => option.type !== 'parent').map(option => option.option.value);
+        // Groups are compared only with groups, so a group may share a value with an option.
+        const groupValues = options.filter(isOptionGroup).map(group => group.value);
+        return {
+          listOptions: flatOptions,
+          parentMap,
+          originals,
+          originalGroups,
+          hasDuplicateValues: new Set(values).size !== values.length,
+          hasDuplicateGroupValues: new Set(groupValues).size !== groupValues.length,
+        };
+      }, [options]);
+
+    // Check the options inside groups too, not only the top-level entries.
+    checkOptionValueField(
+      'OptionList',
+      'options',
+      listOptions.filter(option => option.type !== 'parent').map(option => option.option)
+    );
+    if (hasDuplicateValues) {
+      warnOnce('OptionList', 'Every option must have a unique `value`. The component may work incorrectly.');
+    }
+    if (hasDuplicateGroupValues) {
+      warnOnce('OptionList', 'Every option group must have a unique `value`. The component may work incorrectly.');
+    }
+
+    // Maps an option the list returns back to the consumer's object. Options from `options` map to their originals;
+    // anything else already came from the consumer through `selectedOptions`.
+    const toPublicOption = useCallback(
+      (option: OptionDefinition): OptionListProps.Option => originals.get(option) ?? (option as OptionListProps.Option),
+      [originals]
+    );
+    const toPublicGroup = useCallback(
+      (group: OptionGroup): OptionListProps.OptionGroup =>
+        originalGroups.get(group) ?? (group as OptionListProps.OptionGroup),
+      [originalGroups]
+    );
+
+    const [selectedOptions = EMPTY_SELECTION, setSelectedOptions] = useControllable(
+      controlledSelectedOptions,
+      onChange,
+      EMPTY_SELECTION,
+      { componentName: 'OptionList', controlledProp: 'selectedOptions', changeHandler: 'onChange' }
+    );
+
+    const selection =
+      selectionType === 'multi'
+        ? multiSelection(selectedOptions, { options: listOptions, interactiveGroups: true })
+        : singleSelection(selectedOptions);
+
+    const { listRef, listProps, scrollToIndex, highlightType, announcement, getOptionProps, getRootProps } =
+      useOptionList({
+        options: listOptions,
+        selection,
+        onSelect: option => {
+          const nextSelectedOptions = selection.getNextSelection(option).map(toPublicOption);
+          setSelectedOptions(nextSelectedOptions);
+          fireNonCancelableEvent(onChange, { selectedOptions: nextSelectedOptions });
+        },
+        getParent: option => parentMap.get(option)?.option as OptionGroup | undefined,
+        selectedAriaLabel: i18n('i18nStrings.selectedAriaLabel', i18nStrings?.selectedAriaLabel),
+        // The consumer receives its own option and group objects, as with `renderOption`.
+        renderHighlightedAriaLive:
+          renderHighlightedAriaLive &&
+          ((option, group) =>
+            renderHighlightedAriaLive(
+              isGroup(option) ? toPublicGroup(option) : toPublicOption(option),
+              group && toPublicGroup(group)
+            )),
+      });
+    useForwardFocus(ref, listRef);
+
+    const renderOriginalOption = useMemo<ListboxRenderOption | undefined>(() => {
+      if (!renderOption) {
+        return undefined;
+      }
+      const toGroupItem = (item: ListboxGroupItem): OptionListProps.OptionGroupItem => ({
+        ...item,
+        option: toPublicGroup(item.option),
+      });
+      return ({ item }) => {
+        if (item.type === 'item') {
+          const parent = item.parent && toGroupItem(item.parent);
+          return renderOption({ item: { ...item, option: toPublicOption(item.option), parent } });
+        }
+        if (item.type === 'group') {
+          return renderOption({ item: toGroupItem(item) });
+        }
+        // The listbox renders only options and group headers; it has no trigger or select-all item.
+        return null;
+      };
+    }, [renderOption, toPublicOption, toPublicGroup]);
+
+    return (
+      <div
+        {...baseProps}
+        className={clsx(baseProps.className, styles.root, testClasses.root)}
+        ref={__internalRootRef}
+        {...getRootProps()}
+      >
+        <PlainList
+          ref={scrollToIndex}
+          listProps={{ ...listProps, ariaLabel, ariaLabelledby, ariaDescribedby }}
+          filteredOptions={listOptions}
+          filteringValue=""
+          highlightType={highlightType}
+          selectionType={selection.selectionType}
+          isMultiSelect={listProps.isMultiSelect}
+          screenReaderContent={announcement}
+          renderOption={renderOriginalOption}
+          scrollStrategy="ancestors"
+          getOptionProps={(option, index) => ({
+            ...getOptionProps(option, index),
+            // There is no dropdown border above the list, so the first item has no top divider.
+            hideTopDivider: index === 0,
+            className: option.type === 'parent' ? testClasses['group-header'] : testClasses.option,
+            'data-value': option.option.value,
+          })}
+        />
+      </div>
+    );
+  }
+);
+
+export default InternalOptionList;
diff --git a/src/option-list/styles.scss b/src/option-list/styles.scss
new file mode 100644
index 00000000000..3149d4ea797
--- /dev/null
+++ b/src/option-list/styles.scss
@@ -0,0 +1,11 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+
+@use '../internal/styles' as styles;
+
+.root {
+  @include styles.styles-reset;
+  display: block;
+}
diff --git a/src/option-list/test-classes/styles.scss b/src/option-list/test-classes/styles.scss
new file mode 100644
index 00000000000..a9e28fbeae3
--- /dev/null
+++ b/src/option-list/test-classes/styles.scss
@@ -0,0 +1,9 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+.root,
+.option,
+.group-header {
+  /* used in test-utils */
+}
diff --git a/src/option-list/use-option-list.ts b/src/option-list/use-option-list.ts
new file mode 100644
index 00000000000..201681fc014
--- /dev/null
+++ b/src/option-list/use-option-list.ts
@@ -0,0 +1,104 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { ListElementProps } from '../internal/components/listbox/interfaces';
+import { SelectionModel } from '../internal/components/listbox/selection/interfaces';
+import { useListbox, UseListboxProps } from '../internal/components/listbox/use-listbox';
+import { useTypeAhead } from '../internal/components/listbox/use-type-ahead';
+import { DropdownOption } from '../internal/components/option/interfaces';
+
+interface UseOptionListProps
+  extends Pick<UseListboxProps, 'getParent' | 'selectedAriaLabel' | 'renderHighlightedAriaLive'> {
+  /** Flattened options in list order. */
+  options: ReadonlyArray<DropdownOption>;
+  selection: SelectionModel;
+  /** Called with the interactive option the user chose. */
+  onSelect: (option: DropdownOption) => void;
+}
+
+/**
+ * The list state of OptionList: the shared `useListbox` with OptionList's settings, plus the parts of a list that is
+ * always visible. The list is a tab stop; keyboard, mouse and aria-activedescendant come from `useListbox`.
+ * This hook adds focus and blur, the mouse-leave reset and type-ahead.
+ */
+export function useOptionList({
+  options,
+  selection,
+  onSelect,
+  getParent,
+  selectedAriaLabel,
+  renderHighlightedAriaLive,
+}: UseOptionListProps) {
+  const {
+    listRef,
+    getListProps,
+    scrollToIndex,
+    highlightType,
+    announcement,
+    getOptionProps,
+    highlightedOption,
+    highlight,
+    selectedOptions,
+  } = useListbox({
+    options,
+    selectedOptions: selection.selectedOptions,
+    selection,
+    interactiveGroups: selection.interactiveGroups,
+    onSelect,
+    // When the list has focus, Space always chooses.
+    spaceSelects: 'always',
+    getParent,
+    selectedAriaLabel,
+    renderHighlightedAriaLive,
+  });
+
+  // Focus entry, like opening Select or Multiselect with the keyboard: highlight the first selected option (in
+  // selection order) and scroll it into view, or the first option when nothing in the list is selected.
+  // A highlight that is already there, such as a hover highlight, is kept, so a click selects the hovered option.
+  const onFocus = () => {
+    if (highlightedOption) {
+      return;
+    }
+    const firstSelected = selectedOptions.find(option => options.includes(option));
+    if (firstSelected) {
+      highlight.highlightOptionWithKeyboard(firstSelected);
+    } else {
+      highlight.goHomeWithKeyboard();
+    }
+  };
+
+  const listProps: ListElementProps = {
+    ...getListProps({ withKeyboard: true }),
+    onFocus,
+    // Like closing Select or Multiselect, leaving the list clears the highlight.
+    onBlur: () => highlight.resetHighlightWithKeyboard(),
+    open: true,
+    // The list element is a tab stop without dropdown corners.
+    embedded: true,
+    isMultiSelect: selection.selectionType === 'multi' || undefined,
+  };
+
+  // Attached to the root, not the list, so leaving the whole component clears a hover highlight.
+  const onMouseLeave = () => {
+    if (listRef.current !== document.activeElement) {
+      highlight.resetHighlightWithKeyboard();
+    }
+  };
+
+  const onTypeAhead = useTypeAhead({
+    isEnabled: true,
+    options,
+    highlightOption: highlight.highlightOptionWithKeyboard,
+    highlightedOption: highlightedOption?.option,
+    interactiveGroups: selection.interactiveGroups,
+  });
+
+  return {
+    listRef,
+    listProps,
+    scrollToIndex,
+    highlightType,
+    announcement,
+    getOptionProps,
+    getRootProps: () => ({ onKeyDown: onTypeAhead, onMouseLeave }),
+  };
+}
diff --git a/src/test-utils/dom/option-list/index.ts b/src/test-utils/dom/option-list/index.ts
new file mode 100644
index 00000000000..76da0cb4882
--- /dev/null
+++ b/src/test-utils/dom/option-list/index.ts
@@ -0,0 +1,132 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { ComponentWrapper, ElementWrapper, usesDom } from '@cloudscape-design/test-utils-core/dom';
+import { escapeSelector } from '@cloudscape-design/test-utils-core/utils';
+
+import OptionWrapper from '../internal/option.js';
+
+import selectableItemsStyles from '../../../internal/components/selectable-item/styles.selectors.js';
+import styles from '../../../option-list/test-classes/styles.selectors.js';
+
+export class OptionListOptionWrapper extends ComponentWrapper {
+  /**
+   * Returns the option label.
+   */
+  findLabel(): ElementWrapper | null {
+    return this.findOptionContent()?.findLabel() ?? null;
+  }
+
+  /**
+   * Returns the option description.
+   */
+  findDescription(): ElementWrapper | null {
+    return this.findOptionContent()?.findDescription() ?? null;
+  }
+
+  /**
+   * Returns the option label tag.
+   */
+  findLabelTag(): ElementWrapper | null {
+    return this.findOptionContent()?.findLabelTag() ?? null;
+  }
+
+  /**
+   * Returns the option tags.
+   */
+  findTags(): Array<ElementWrapper> {
+    return this.findOptionContent()?.findTags() ?? [];
+  }
+
+  /**
+   * Returns `true` if the option is selected. A group header in multi selection is selected when all its options are selected.
+   */
+  @usesDom
+  isSelected(): boolean {
+    return this.element.classList.contains(selectableItemsStyles.selected);
+  }
+
+  /**
+   * Returns `true` if the option is highlighted.
+   */
+  @usesDom
+  isHighlighted(): boolean {
+    return this.element.classList.contains(selectableItemsStyles.highlighted);
+  }
+
+  /**
+   * Returns `true` if the option is disabled.
+   */
+  @usesDom
+  isDisabled(): boolean {
+    return this.element.classList.contains(selectableItemsStyles.disabled);
+  }
+
+  private findOptionContent(): OptionWrapper | null {
+    return this.findComponent(`.${OptionWrapper.rootSelector}`, OptionWrapper);
+  }
+}
+
+export default class OptionListWrapper extends ComponentWrapper {
+  static rootSelector: string = styles.root;
+
+  /**
+   * Returns all options. Group headers are not included.
+   */
+  findOptions(): Array<OptionListOptionWrapper> {
+    return this.findAllByClassName(styles.option).map(wrapper => new OptionListOptionWrapper(wrapper.getElement()));
+  }
+
+  /**
+   * Returns an option for a given index. Group headers are not counted.
+   *
+   * @param index 1-based index of the option to return.
+   */
+  findOptionByIndex(index: number): OptionListOptionWrapper | null {
+    return this.findComponent(`.${styles.option}[data-test-index="${index}"]`, OptionListOptionWrapper);
+  }
+
+  /**
+   * Returns an option for a given value.
+   *
+   * @param value The `value` of the option.
+   */
+  findOptionByValue(value: string): OptionListOptionWrapper | null {
+    const escapedValue = escapeSelector(value);
+    return this.findComponent(`.${styles.option}[data-value="${escapedValue}"]`, OptionListOptionWrapper);
+  }
+
+  /**
+   * Returns all selected options. Group headers are not included.
+   */
+  findSelectedOptions(): Array<OptionListOptionWrapper> {
+    return this.findAll(`.${styles.option}.${selectableItemsStyles.selected}`).map(
+      wrapper => new OptionListOptionWrapper(wrapper.getElement())
+    );
+  }
+
+  /**
+   * Returns the highlighted option. Group headers are not included.
+   */
+  findHighlightedOption(): OptionListOptionWrapper | null {
+    return this.findComponent(`.${styles.option}.${selectableItemsStyles.highlighted}`, OptionListOptionWrapper);
+  }
+
+  /**
+   * Returns all option group headers.
+   */
+  findGroupHeaders(): Array<OptionListOptionWrapper> {
+    return this.findAllByClassName(styles['group-header']).map(
+      wrapper => new OptionListOptionWrapper(wrapper.getElement())
+    );
+  }
+
+  /**
+   * Returns an option group header for a given value.
+   *
+   * @param value The `value` of the option group.
+   */
+  findGroupHeaderByValue(value: string): OptionListOptionWrapper | null {
+    const escapedValue = escapeSelector(value);
+    return this.findComponent(`.${styles['group-header']}[data-value="${escapedValue}"]`, OptionListOptionWrapper);
+  }
+}

From a8bb2531cf733bd8de7cb72e30e420f62a4d2343 Mon Sep 17 00:00:00 2001
From: Amanuel Sisay <amanabiy@amazon.de>
Date: Wed, 4 Nov 2026 10:01:56 +0100
Subject: [PATCH 3/5] chore: Add OptionList dev pages

Simple, scroll, and single and multi selection permutation pages. The integration tests use the simple and scroll pages.
---
 pages/option-list/permutations-common.tsx     |  62 +++++
 pages/option-list/permutations-multi.page.tsx |  33 +++
 .../option-list/permutations-single.page.tsx  |  33 +++
 pages/option-list/scroll.page.tsx             | 216 ++++++++++++++++++
 pages/option-list/scroll.scss                 |  15 ++
 pages/option-list/simple.page.tsx             |  88 +++++++
 6 files changed, 447 insertions(+)
 create mode 100644 pages/option-list/permutations-common.tsx
 create mode 100644 pages/option-list/permutations-multi.page.tsx
 create mode 100644 pages/option-list/permutations-single.page.tsx
 create mode 100644 pages/option-list/scroll.page.tsx
 create mode 100644 pages/option-list/scroll.scss
 create mode 100644 pages/option-list/simple.page.tsx

diff --git a/pages/option-list/permutations-common.tsx b/pages/option-list/permutations-common.tsx
new file mode 100644
index 00000000000..12f1fe3dedd
--- /dev/null
+++ b/pages/option-list/permutations-common.tsx
@@ -0,0 +1,62 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import Icon from '~components/icon';
+import OptionList, { OptionListProps } from '~components/option-list';
+
+import { PermutationsPage } from '../app/templates';
+import PermutationsView from '../utils/permutations-view';
+
+export const plain: OptionListProps.Option[] = [
+  { value: '1', label: 'Reduce cost' },
+  { value: '2', label: 'Improve performance', description: 'Prioritize latency and throughput.' },
+  {
+    value: '3',
+    label: 'Increase reliability across every Region and Availability Zone that hosts the workload',
+    description: 'A long label and a long description that wrap onto multiple lines on narrow containers.',
+  },
+  { value: '4', label: 'Strengthen security' },
+];
+
+const withIcons = plain.map(option => ({ ...option, icon: <Icon name="settings" /> }));
+
+const withTags = plain.map(option => ({ ...option, labelTag: '128 GB', tags: ['CPU-v2', '2 GB RAM'] }));
+
+const withDisabled = plain.map(option =>
+  option.value === '2' || option.value === '4'
+    ? { ...option, disabled: true, disabledReason: option.value === '4' ? 'Requires Enterprise support' : undefined }
+    : option
+);
+
+export const grouped: OptionListProps.Options = [
+  { value: 'group-1', label: 'Goals', options: plain.slice(0, 2) },
+  { value: 'group-2', label: 'More goals', options: plain.slice(2) },
+];
+
+export const allOptions = [plain, withIcons, withTags, withDisabled, grouped];
+
+export const renderOption: OptionListProps['renderOption'] = ({ item }) => <strong>{item.option.label}</strong>;
+
+export type OptionListPermutation = OptionListProps & { width: number };
+
+export function OptionListPermutations({
+  title,
+  permutations,
+}: {
+  title: string;
+  permutations: ReadonlyArray<OptionListPermutation>;
+}) {
+  return (
+    <PermutationsPage title={title} screenshotArea={{ disableAnimations: true }}>
+      <PermutationsView
+        permutations={permutations}
+        render={({ width, ...props }) => (
+          <div style={{ inlineSize: width }}>
+            <OptionList {...props} ariaLabel="Goals" onChange={() => {}} />
+          </div>
+        )}
+      />
+    </PermutationsPage>
+  );
+}
diff --git a/pages/option-list/permutations-multi.page.tsx b/pages/option-list/permutations-multi.page.tsx
new file mode 100644
index 00000000000..4712d93f26e
--- /dev/null
+++ b/pages/option-list/permutations-multi.page.tsx
@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import createPermutations from '../utils/permutations';
+import {
+  allOptions,
+  grouped,
+  OptionListPermutation,
+  OptionListPermutations,
+  plain,
+  renderOption,
+} from './permutations-common';
+
+const permutations = createPermutations<OptionListPermutation>([
+  {
+    width: [240, 480],
+    options: allOptions,
+    selectionType: ['multi'],
+    selectedOptions: [[], [plain[1]], [plain[1], plain[2]]],
+  },
+  {
+    width: [240],
+    options: [grouped],
+    selectionType: ['multi'],
+    selectedOptions: [[plain[1]]],
+    renderOption: [renderOption],
+  },
+]);
+
+export default function OptionListMultiPermutationsPage() {
+  return <OptionListPermutations title="OptionList permutations: multi selection" permutations={permutations} />;
+}
diff --git a/pages/option-list/permutations-single.page.tsx b/pages/option-list/permutations-single.page.tsx
new file mode 100644
index 00000000000..46d44aaa944
--- /dev/null
+++ b/pages/option-list/permutations-single.page.tsx
@@ -0,0 +1,33 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import createPermutations from '../utils/permutations';
+import {
+  allOptions,
+  grouped,
+  OptionListPermutation,
+  OptionListPermutations,
+  plain,
+  renderOption,
+} from './permutations-common';
+
+const permutations = createPermutations<OptionListPermutation>([
+  {
+    width: [240, 480],
+    options: allOptions,
+    selectionType: ['single'],
+    selectedOptions: [[], [plain[1]]],
+  },
+  {
+    width: [240],
+    options: [grouped],
+    selectionType: ['single'],
+    selectedOptions: [[plain[1]]],
+    renderOption: [renderOption],
+  },
+]);
+
+export default function OptionListSinglePermutationsPage() {
+  return <OptionListPermutations title="OptionList permutations: single selection" permutations={permutations} />;
+}
diff --git a/pages/option-list/scroll.page.tsx b/pages/option-list/scroll.page.tsx
new file mode 100644
index 00000000000..aab31aa4c02
--- /dev/null
+++ b/pages/option-list/scroll.page.tsx
@@ -0,0 +1,216 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useContext, useEffect, useRef, useState } from 'react';
+
+import Button, { ButtonProps } from '~components/button';
+import Dropdown from '~components/dropdown';
+import FormField from '~components/form-field';
+import Header from '~components/header';
+import OptionList, { OptionListProps } from '~components/option-list';
+import SegmentedControl from '~components/segmented-control';
+import SpaceBetween from '~components/space-between';
+
+import AppContext, { AppContextType } from '../app/app-context';
+import { SimplePage } from '../app/templates';
+
+import styles from './scroll.scss';
+
+/**
+ * Where the scrolling happens:
+ * - `wrapper`: a wrapper div with a fixed height and `overflow: auto`.
+ * - `page`: no container, the page scrolls.
+ * - `dropdown`: the list is the content of a Dropdown opened by a button.
+ */
+type Container = 'wrapper' | 'page' | 'dropdown';
+type Preselected = 'none' | 'near-end';
+
+type PageContext = React.Context<
+  AppContextType<{
+    container?: Container;
+    expandToViewport?: boolean;
+    selectionType?: OptionListProps.SelectionType;
+    preselected?: Preselected;
+  }>
+>;
+
+const options: OptionListProps.Option[] = Array.from({ length: 100 }, (_, index) => ({
+  value: `option-${index + 1}`,
+  label: `Option ${index + 1}`,
+}));
+
+function DropdownOptionList({
+  expandToViewport,
+  list,
+  listRef,
+}: {
+  expandToViewport: boolean;
+  list: (props: { onChange: () => void }) => React.ReactNode;
+  listRef: React.RefObject<OptionListProps.Ref>;
+}) {
+  const [open, setOpen] = useState(false);
+  const triggerRef = useRef<ButtonProps.Ref>(null);
+
+  // Move focus into the list once the Dropdown has rendered its content.
+  useEffect(() => {
+    if (open) {
+      listRef.current?.focus();
+    }
+  }, [open, listRef]);
+
+  const close = (returnFocus: boolean) => {
+    setOpen(false);
+    if (returnFocus) {
+      triggerRef.current?.focus();
+    }
+  };
+
+  return (
+    <Dropdown
+      open={open}
+      onOutsideClick={() => close(false)}
+      onEscape={() => close(true)}
+      minWidth={320}
+      expandToViewport={expandToViewport}
+      trigger={
+        <Button
+          id="dropdown-trigger"
+          ref={triggerRef}
+          ariaExpanded={open}
+          ariaHaspopup="listbox"
+          iconName="caret-down-filled"
+          iconAlign="right"
+          onClick={() => setOpen(!open)}
+        >
+          Choose an option
+        </Button>
+      }
+      content={<div className={styles['dropdown-content']}>{list({ onChange: () => close(true) })}</div>}
+    />
+  );
+}
+
+function ConfiguredOptionList({
+  container,
+  expandToViewport,
+  selectionType,
+  preselected,
+}: {
+  container: Container;
+  expandToViewport: boolean;
+  selectionType: OptionListProps.SelectionType;
+  preselected: Preselected;
+}) {
+  const [selectedOptions, setSelectedOptions] = useState<ReadonlyArray<OptionListProps.Option>>(
+    preselected === 'near-end' ? [options[80]] : []
+  );
+  const listRef = useRef<OptionListProps.Ref>(null);
+
+  const list = ({ onChange }: { onChange?: () => void } = {}) => (
+    <OptionList
+      ref={listRef}
+      data-testid="option-list"
+      ariaLabelledby="option-list-heading"
+      selectionType={selectionType}
+      options={options}
+      selectedOptions={selectedOptions}
+      onChange={({ detail }) => {
+        setSelectedOptions(detail.selectedOptions);
+        onChange?.();
+      }}
+    />
+  );
+
+  return (
+    <SpaceBetween size="xs">
+      {/* Integ tests click the heading, then press Tab to move keyboard focus into the list. */}
+      <Header variant="h2" id="option-list-heading">
+        Long list
+      </Header>
+      {container === 'wrapper' && (
+        <div id="scroll-container" className={styles['fixed-height']}>
+          {list()}
+        </div>
+      )}
+      {container === 'page' && list()}
+      {container === 'dropdown' && (
+        <DropdownOptionList expandToViewport={expandToViewport} list={list} listRef={listRef} />
+      )}
+      <div data-testid="selected-value">
+        Selected: {selectedOptions.map(option => option.value).join(', ') || 'none'}
+      </div>
+    </SpaceBetween>
+  );
+}
+
+export default function OptionListScrollPage() {
+  const { urlParams, setUrlParams } = useContext(AppContext as PageContext);
+  const container = urlParams.container ?? 'wrapper';
+  const expandToViewport = urlParams.expandToViewport ?? false;
+  const selectionType = urlParams.selectionType ?? 'single';
+  const preselected = urlParams.preselected ?? 'none';
+
+  return (
+    <SimplePage
+      title="Option list: scrolling long lists"
+      settings={
+        <SpaceBetween size="m">
+          <FormField label="Scroll container">
+            <SegmentedControl
+              selectedId={container}
+              onChange={({ detail }) => setUrlParams({ container: detail.selectedId as Container })}
+              options={[
+                { id: 'wrapper', text: 'Wrapper' },
+                { id: 'page', text: 'Page' },
+                { id: 'dropdown', text: 'Dropdown' },
+              ]}
+            />
+          </FormField>
+          <FormField label="Expand to viewport (Dropdown only)">
+            <SegmentedControl
+              selectedId={`${expandToViewport}`}
+              onChange={({ detail }) => setUrlParams({ expandToViewport: detail.selectedId === 'true' })}
+              options={[
+                { id: 'false', text: 'No' },
+                { id: 'true', text: 'Yes' },
+              ]}
+            />
+          </FormField>
+          <FormField label="Selection type">
+            <SegmentedControl
+              selectedId={selectionType}
+              onChange={({ detail }) =>
+                setUrlParams({ selectionType: detail.selectedId as OptionListProps.SelectionType })
+              }
+              options={[
+                { id: 'single', text: 'Single' },
+                { id: 'multi', text: 'Multi' },
+              ]}
+            />
+          </FormField>
+          <FormField label="Already selected">
+            <SegmentedControl
+              selectedId={preselected}
+              onChange={({ detail }) => setUrlParams({ preselected: detail.selectedId as Preselected })}
+              options={[
+                { id: 'none', text: 'None' },
+                { id: 'near-end', text: 'Option 81' },
+              ]}
+            />
+          </FormField>
+        </SpaceBetween>
+      }
+      screenshotArea={{}}
+    >
+      <div style={{ maxInlineSize: 520 }}>
+        {/* Remount on every configuration change so the initial selection follows the settings. */}
+        <ConfiguredOptionList
+          key={`${container}-${expandToViewport}-${selectionType}-${preselected}`}
+          container={container}
+          expandToViewport={expandToViewport}
+          selectionType={selectionType}
+          preselected={preselected}
+        />
+      </div>
+    </SimplePage>
+  );
+}
diff --git a/pages/option-list/scroll.scss b/pages/option-list/scroll.scss
new file mode 100644
index 00000000000..d52e0391478
--- /dev/null
+++ b/pages/option-list/scroll.scss
@@ -0,0 +1,15 @@
+/*
+ Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ SPDX-License-Identifier: Apache-2.0
+*/
+
+// A scroll container for the list. Applied to a wrapper div.
+.fixed-height {
+  block-size: 240px;
+  overflow: auto;
+}
+
+// Lets the list scroll inside the Dropdown content instead of overflowing it.
+.dropdown-content {
+  overflow: auto;
+}
diff --git a/pages/option-list/simple.page.tsx b/pages/option-list/simple.page.tsx
new file mode 100644
index 00000000000..2dc7a044741
--- /dev/null
+++ b/pages/option-list/simple.page.tsx
@@ -0,0 +1,88 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useState } from 'react';
+
+import Box from '~components/box';
+import Header from '~components/header';
+import Icon from '~components/icon';
+import OptionList, { OptionListProps } from '~components/option-list';
+import SpaceBetween from '~components/space-between';
+
+import { SimplePage } from '../app/templates';
+
+const goals: OptionListProps.Option[] = [
+  {
+    value: 'cost',
+    label: 'Reduce cost',
+    description: 'Prioritize cheaper instance types and storage tiers.',
+    icon: <Icon name="settings" />,
+  },
+  { value: 'performance', label: 'Improve performance', description: 'Prioritize latency and throughput.' },
+  { value: 'reliability', label: 'Increase reliability', description: 'Add redundancy across Availability Zones.' },
+  { value: 'security', label: 'Strengthen security', description: 'Tighten IAM policies and encryption settings.' },
+];
+
+const services: OptionListProps.Options = [
+  {
+    value: 'compute',
+    label: 'Compute',
+    options: [
+      { value: 'ec2', label: 'Amazon EC2' },
+      { value: 'lambda', label: 'AWS Lambda' },
+    ],
+  },
+  {
+    value: 'storage',
+    label: 'Storage',
+    options: [
+      { value: 's3', label: 'Amazon S3' },
+      { value: 'efs', label: 'Amazon EFS', disabled: true, disabledReason: 'Not available in this Region.' },
+    ],
+  },
+];
+
+function Section({
+  id,
+  title,
+  options,
+  selectionType,
+}: {
+  id: string;
+  title: string;
+  options: OptionListProps.Options;
+  selectionType: OptionListProps.SelectionType;
+}) {
+  const [selectedOptions, setSelectedOptions] = useState<ReadonlyArray<OptionListProps.Option>>([]);
+  return (
+    <SpaceBetween size="xs">
+      <Header variant="h2" id={`${id}-heading`}>
+        {title}
+      </Header>
+      <OptionList
+        data-testid={id}
+        ariaLabelledby={`${id}-heading`}
+        options={options}
+        selectionType={selectionType}
+        selectedOptions={selectedOptions}
+        onChange={({ detail }) => setSelectedOptions(detail.selectedOptions)}
+      />
+      <Box variant="small" data-testid={`${id}-value`}>
+        Selected: {selectedOptions.map(option => option.value).join(', ') || 'none'}
+      </Box>
+    </SpaceBetween>
+  );
+}
+
+export default function OptionListSimplePage() {
+  return (
+    <SimplePage title="Option list" screenshotArea={{}}>
+      <div style={{ maxInlineSize: 520 }}>
+        <SpaceBetween size="xl">
+          <Section id="single" title="Single selection" options={goals} selectionType="single" />
+          <Section id="multi" title="Multi selection" options={goals} selectionType="multi" />
+          <Section id="groups" title="Multi selection with groups" options={services} selectionType="multi" />
+        </SpaceBetween>
+      </div>
+    </SimplePage>
+  );
+}

From 7ef8f3250c01e0adf140a39d0a795b12dd9c5b11 Mon Sep 17 00:00:00 2001
From: Amanuel Sisay <amanabiy@amazon.de>
Date: Wed, 4 Nov 2026 10:01:56 +0100
Subject: [PATCH 4/5] test: Add OptionList unit and integration tests

---
 .../listbox/__tests__/plain-list.test.tsx     |  70 +++++
 .../listbox/__tests__/scroll-to-index.test.ts |  43 ++-
 .../__tests__/options-list.test.tsx           |  10 +
 .../__tests__/use-keyboard.test.ts            |  10 +
 .../__integ__/option-list-scroll.test.ts      | 134 ++++++++
 src/option-list/__integ__/option-list.test.ts |  60 ++++
 src/option-list/__tests__/common.tsx          | 102 ++++++
 src/option-list/__tests__/disabled.test.tsx   | 108 +++++++
 .../__tests__/group-state.test.tsx            | 165 ++++++++++
 src/option-list/__tests__/highlight.test.tsx  | 163 ++++++++++
 src/option-list/__tests__/i18n.test.tsx       |  32 ++
 src/option-list/__tests__/keyboard.test.tsx   | 108 +++++++
 .../__tests__/option-list-a11y.test.tsx       |  97 ++++++
 .../__tests__/option-list.test.tsx            | 297 ++++++++++++++++++
 .../__tests__/render-option.test.tsx          | 103 ++++++
 15 files changed, 1501 insertions(+), 1 deletion(-)
 create mode 100644 src/internal/components/listbox/__tests__/plain-list.test.tsx
 create mode 100644 src/option-list/__integ__/option-list-scroll.test.ts
 create mode 100644 src/option-list/__integ__/option-list.test.ts
 create mode 100644 src/option-list/__tests__/common.tsx
 create mode 100644 src/option-list/__tests__/disabled.test.tsx
 create mode 100644 src/option-list/__tests__/group-state.test.tsx
 create mode 100644 src/option-list/__tests__/highlight.test.tsx
 create mode 100644 src/option-list/__tests__/i18n.test.tsx
 create mode 100644 src/option-list/__tests__/keyboard.test.tsx
 create mode 100644 src/option-list/__tests__/option-list-a11y.test.tsx
 create mode 100644 src/option-list/__tests__/option-list.test.tsx
 create mode 100644 src/option-list/__tests__/render-option.test.tsx

diff --git a/src/internal/components/listbox/__tests__/plain-list.test.tsx b/src/internal/components/listbox/__tests__/plain-list.test.tsx
new file mode 100644
index 00000000000..58993575e1a
--- /dev/null
+++ b/src/internal/components/listbox/__tests__/plain-list.test.tsx
@@ -0,0 +1,70 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { act, render } from '@testing-library/react';
+
+import PlainList from '../../../../../lib/components/internal/components/listbox/parts/plain-list';
+import { flattenOptions } from '../../../../../lib/components/internal/components/option/utils/flatten-options';
+import { HighlightType } from '../../../../../lib/components/internal/components/options-list/utils/use-highlight-option';
+import type { GetOptionProps, ScrollToIndexRef } from '../interfaces';
+import type { ItemProps } from '../parts/item';
+import type { ListProps } from '../parts/plain-list';
+
+const { flatOptions } = flattenOptions([
+  { value: 'a', label: 'A' },
+  { value: 'b', label: 'B' },
+]);
+
+const getOptionProps: GetOptionProps = (option, index) => ({ option, index, 'data-mouse-target': index }) as ItemProps;
+
+function renderPlainList(scrollStrategy?: ListProps['scrollStrategy']) {
+  const scrollToIndex = React.createRef<ScrollToIndexRef>();
+  const listRef = React.createRef<HTMLDivElement>();
+  render(
+    <PlainList
+      ref={scrollToIndex}
+      listProps={{ ref: listRef, open: true, embedded: true }}
+      getOptionProps={getOptionProps}
+      filteredOptions={flatOptions}
+      filteringValue=""
+      highlightType={new HighlightType('keyboard')}
+      scrollStrategy={scrollStrategy}
+    />
+  );
+  const list = listRef.current!;
+  const item = list.querySelector<HTMLElement>('[data-mouse-target="1"]')!;
+  return { scrollTo: (index: number) => act(() => scrollToIndex.current!(index)), list, item };
+}
+
+describe('PlainList scrollStrategy', () => {
+  const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+  let scrollIntoView: jest.Mock;
+
+  beforeEach(() => {
+    scrollIntoView = HTMLElement.prototype.scrollIntoView = jest.fn();
+  });
+  afterEach(() => {
+    HTMLElement.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  test('ancestors: scrolls the option into view through all scrollable ancestors', () => {
+    const { scrollTo, list, item } = renderPlainList('ancestors');
+    list.scrollBy = jest.fn();
+    scrollTo(1);
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(scrollIntoView.mock.instances[0]).toBe(item);
+    expect(list.scrollBy).not.toHaveBeenCalled();
+  });
+
+  test('scrolls only the list by default', () => {
+    const { scrollTo, list, item } = renderPlainList();
+    // jsdom has no layout, so give the list a height and place the option below its visible area.
+    Object.defineProperty(list, 'clientHeight', { value: 100 });
+    list.getBoundingClientRect = () => ({ top: 0, bottom: 100, height: 100 }) as DOMRect;
+    item.getBoundingClientRect = () => ({ top: 200, bottom: 250, height: 50 }) as DOMRect;
+    list.scrollBy = jest.fn();
+    scrollTo(1);
+    expect(list.scrollBy).toHaveBeenCalledWith({ top: 150 });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/internal/components/listbox/__tests__/scroll-to-index.test.ts b/src/internal/components/listbox/__tests__/scroll-to-index.test.ts
index a1699e3d6e5..6ad716fd64e 100644
--- a/src/internal/components/listbox/__tests__/scroll-to-index.test.ts
+++ b/src/internal/components/listbox/__tests__/scroll-to-index.test.ts
@@ -1,6 +1,6 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
-import scrollToIndex from '../parts/scroll-to-index';
+import scrollToIndex, { scrollOptionIntoView } from '../parts/scroll-to-index';
 
 describe('scroll-to-index', () => {
   function runWith({
@@ -168,3 +168,44 @@ describe('scroll-to-index', () => {
     });
   });
 });
+
+describe('scrollOptionIntoView', () => {
+  const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+  let scrollIntoView: jest.Mock;
+
+  beforeEach(() => {
+    scrollIntoView = HTMLElement.prototype.scrollIntoView = jest.fn();
+  });
+  afterEach(() => {
+    HTMLElement.prototype.scrollIntoView = originalScrollIntoView;
+  });
+
+  function createMenu(mouseTargets: number[]) {
+    const menuEl = document.createElement('div');
+    for (const mouseTarget of mouseTargets) {
+      const item = document.createElement('div');
+      item.dataset.mouseTarget = `${mouseTarget}`;
+      menuEl.appendChild(item);
+    }
+    return menuEl;
+  }
+
+  it('scrolls the option at the index into view through its scrollable ancestors', () => {
+    const menuEl = createMenu([0, 1, 2]);
+    scrollOptionIntoView({ index: 2, menuEl });
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(scrollIntoView.mock.instances[0]).toBe(menuEl.children[2]);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest', inline: 'nearest' });
+  });
+
+  it('does not scroll when nothing is highlighted, even if a non-interactive row uses index -1', () => {
+    // Non-interactive rows such as single-selection group headers render with data-mouse-target="-1".
+    scrollOptionIntoView({ index: -1, menuEl: createMenu([-1, 0, 1]) });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  it('does not scroll when no option has the index', () => {
+    scrollOptionIntoView({ index: 5, menuEl: createMenu([0, 1]) });
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/internal/components/options-list/__tests__/options-list.test.tsx b/src/internal/components/options-list/__tests__/options-list.test.tsx
index 3a2f7160a63..cd6731887d7 100644
--- a/src/internal/components/options-list/__tests__/options-list.test.tsx
+++ b/src/internal/components/options-list/__tests__/options-list.test.tsx
@@ -119,3 +119,13 @@ test('onLoadMore is called when dropdown is open and status type changes to "pen
 
   expect(onLoadMore).toHaveBeenCalledTimes(2);
 });
+
+test('onLoadMore does not fire on open when statusType is omitted', () => {
+  const onLoadMore = jest.fn();
+  render(
+    <OptionsList open={true} onLoadMore={onLoadMore}>
+      <div>Option</div>
+    </OptionsList>
+  );
+  expect(onLoadMore).not.toHaveBeenCalled();
+});
diff --git a/src/internal/components/options-list/__tests__/use-keyboard.test.ts b/src/internal/components/options-list/__tests__/use-keyboard.test.ts
index 086b88938f1..94bbfb12cfd 100644
--- a/src/internal/components/options-list/__tests__/use-keyboard.test.ts
+++ b/src/internal/components/options-list/__tests__/use-keyboard.test.ts
@@ -105,6 +105,16 @@ describe('useMenuKeyboard', () => {
     expect(menuKeys.escape.preventDefault).not.toHaveBeenCalled();
   });
 
+  test('does not stop propagation when onEscape is omitted', () => {
+    const escape = { detail: { keyCode: KeyCode.escape }, preventDefault: jest.fn(), stopPropagation: jest.fn() };
+    const hook = renderHook(useMenuKeyboard, {
+      initialProps: { ...menuInitialProps, onEscape: undefined },
+    });
+    act(() => hook.result.current(escape as any));
+    expect(escape.stopPropagation).not.toHaveBeenCalled();
+    expect(escape.preventDefault).not.toHaveBeenCalled();
+  });
+
   test('should select option when pressing enter', () => {
     const selectOption = jest.fn();
     const hook = renderHook(useMenuKeyboard, {
diff --git a/src/option-list/__integ__/option-list-scroll.test.ts b/src/option-list/__integ__/option-list-scroll.test.ts
new file mode 100644
index 00000000000..be6b07e49c2
--- /dev/null
+++ b/src/option-list/__integ__/option-list-scroll.test.ts
@@ -0,0 +1,134 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BasePageObject } from '@cloudscape-design/browser-test-tools/page-objects';
+import useBrowser from '@cloudscape-design/browser-test-tools/use-browser';
+
+import createWrapper from '../../../lib/components/test-utils/selectors';
+
+const list = createWrapper().findOptionList('[data-testid="option-list"]');
+const listbox = `${list.toSelector()} [role="listbox"]`;
+
+class ScrollPage extends BasePageObject {
+  /** Whether the highlighted option is inside the viewport and inside every scrolling ancestor. */
+  isHighlightVisible() {
+    return this.browser.execute(selector => {
+      const option = document.querySelector(selector);
+      if (!option) {
+        return false;
+      }
+      const rect = option.getBoundingClientRect();
+      const within = (top: number, bottom: number) => rect.top >= top - 1 && rect.bottom <= bottom + 1;
+      for (let parent = option.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && parent.scrollHeight > parent.clientHeight) {
+          const parentRect = parent.getBoundingClientRect();
+          if (!within(parentRect.top + parent.clientTop, parentRect.top + parent.clientTop + parent.clientHeight)) {
+            return false;
+          }
+        }
+      }
+      return within(0, window.innerHeight);
+    }, list.findHighlightedOption().toSelector());
+  }
+
+  getHighlightedText() {
+    return this.getText(list.findHighlightedOption().findLabel().toSelector());
+  }
+
+  /** Scrolls the list's nearest scroll container (or the page) back to the top, away from the highlight. */
+  scrollToTop() {
+    return this.browser.execute(selector => {
+      for (let parent = document.querySelector(selector)!.parentElement; parent; parent = parent.parentElement) {
+        const { overflowY } = getComputedStyle(parent);
+        if ((overflowY === 'auto' || overflowY === 'scroll') && parent.scrollHeight > parent.clientHeight) {
+          parent.scrollTop = 0;
+          return;
+        }
+      }
+      window.scrollTo(0, 0);
+    }, listbox);
+  }
+
+  /** Retries the visibility check for a short time, so it doesn't run before a scroll has settled. */
+  async waitForHighlightVisible() {
+    await this.waitForAssertion(() => expect(this.isHighlightVisible()).resolves.toBe(true));
+  }
+
+  async expectHighlightVisibleAfter(keys: string[], label: string) {
+    await this.keys(keys);
+    await expect(this.getHighlightedText()).resolves.toBe(label);
+    await this.waitForHighlightVisible();
+  }
+
+  async assertKeyboardScrolling() {
+    // Arrow keys call preventDefault, so the browser doesn't scroll on its own: every scroll here comes from the list.
+    await this.expectHighlightVisibleAfter(new Array(30).fill('ArrowDown'), 'Option 31');
+    await this.expectHighlightVisibleAfter(new Array(30).fill('ArrowUp'), 'Option 1');
+
+    // Wrapping around jumps between the two ends of the list.
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 100');
+    await this.expectHighlightVisibleAfter(['ArrowDown'], 'Option 1');
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 100');
+
+    // Scroll away from the highlight, so the next move has to scroll back to it.
+    await this.scrollToTop();
+    await this.expectHighlightVisibleAfter(['ArrowUp'], 'Option 99');
+
+    // Home and End don't call preventDefault, so the browser also starts its native scroll. That scroll is animated
+    // and keeps running after the key press, so it would move the page under any later check. Check them last, and
+    // only check where they move the highlight.
+    await this.keys(['End']);
+    await expect(this.getHighlightedText()).resolves.toBe('Option 100');
+    await this.keys(['Home']);
+    await expect(this.getHighlightedText()).resolves.toBe('Option 1');
+  }
+}
+
+const setupTest = (url: string, testFn: (page: ScrollPage) => Promise<void>) =>
+  useBrowser({ width: 1200, height: 800 }, async browser => {
+    await browser.url(url);
+    const page = new ScrollPage(browser);
+    await page.waitForVisible('h1');
+    await testFn(page);
+  });
+
+describe('OptionList keyboard scrolling', () => {
+  describe.each(['wrapper', 'page'])('container=%s', container => {
+    const focusList = async (page: ScrollPage) => {
+      await page.click('#option-list-heading');
+      await page.keys(['Tab']);
+      await expect(page.isFocused(listbox)).resolves.toBe(true);
+    };
+
+    test(
+      'keeps the highlighted option visible',
+      setupTest(`#/light/option-list/scroll?container=${container}`, async page => {
+        await focusList(page);
+        await page.assertKeyboardScrolling();
+      })
+    );
+
+    test(
+      'focus entry highlights the selected option near the end and scrolls it into view',
+      setupTest(`#/light/option-list/scroll?container=${container}&preselected=near-end`, async page => {
+        await focusList(page);
+        await expect(page.getHighlightedText()).resolves.toBe('Option 81');
+        await page.waitForHighlightVisible();
+      })
+    );
+  });
+
+  describe.each([false, true])('in a Dropdown, expandToViewport=%s', expandToViewport => {
+    test(
+      'keeps the highlighted option visible without scrolling the page on open',
+      setupTest(`#/light/option-list/scroll?container=dropdown&expandToViewport=${expandToViewport}`, async page => {
+        const scrollBefore = await page.getWindowScroll();
+        await page.click('#dropdown-trigger');
+        await page.waitForVisible(listbox);
+        await expect(page.isFocused(listbox)).resolves.toBe(true);
+        await expect(page.getWindowScroll()).resolves.toEqual(scrollBefore);
+        await page.assertKeyboardScrolling();
+      })
+    );
+  });
+});
diff --git a/src/option-list/__integ__/option-list.test.ts b/src/option-list/__integ__/option-list.test.ts
new file mode 100644
index 00000000000..c46d3c2245a
--- /dev/null
+++ b/src/option-list/__integ__/option-list.test.ts
@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { BasePageObject } from '@cloudscape-design/browser-test-tools/page-objects';
+import useBrowser from '@cloudscape-design/browser-test-tools/use-browser';
+
+import createWrapper from '../../../lib/components/test-utils/selectors';
+
+const wrapper = createWrapper();
+const singleList = wrapper.findOptionList('[data-testid="single"]');
+const multiList = wrapper.findOptionList('[data-testid="multi"]');
+const groupsList = wrapper.findOptionList('[data-testid="groups"]');
+const listbox = (list: typeof singleList) => `${list.toSelector()} [role="listbox"]`;
+
+const setupTest = (testFn: (page: BasePageObject) => Promise<void>) =>
+  useBrowser(async browser => {
+    await browser.url('#/light/option-list/simple');
+    const page = new BasePageObject(browser);
+    await page.waitForVisible(singleList.toSelector());
+    await testFn(page);
+  });
+
+describe('OptionList', () => {
+  test(
+    'selects an option with a click anywhere on the row',
+    setupTest(async page => {
+      await page.click(singleList.findOptionByValue('performance').findDescription().toSelector());
+      await expect(page.getText('[data-testid="single-value"]')).resolves.toBe('Selected: performance');
+      await expect(page.getElementsCount(singleList.findSelectedOptions().toSelector())).resolves.toBe(1);
+    })
+  );
+
+  test(
+    'selects with the keyboard: Tab into the list, arrows move, Enter selects',
+    setupTest(async page => {
+      await page.click('#single-heading');
+      await page.keys(['Tab']);
+      await expect(page.isFocused(listbox(singleList))).resolves.toBe(true);
+      await page.keys(['ArrowDown', 'ArrowDown', 'Enter']);
+      await expect(page.getText('[data-testid="single-value"]')).resolves.toBe('Selected: reliability');
+    })
+  );
+
+  test(
+    'Tab leaves the list after one stop',
+    setupTest(async page => {
+      await page.click('#single-heading');
+      await page.keys(['Tab', 'Tab']);
+      await expect(page.isFocused(listbox(singleList))).resolves.toBe(false);
+      await expect(page.isFocused(listbox(multiList))).resolves.toBe(true);
+    })
+  );
+
+  test(
+    'clicking a group header selects its enabled options',
+    setupTest(async page => {
+      await page.click(groupsList.findGroupHeaderByValue('storage').toSelector());
+      await expect(page.getText('[data-testid="groups-value"]')).resolves.toBe('Selected: s3');
+    })
+  );
+});
diff --git a/src/option-list/__tests__/common.tsx b/src/option-list/__tests__/common.tsx
new file mode 100644
index 00000000000..2158a8ca420
--- /dev/null
+++ b/src/option-list/__tests__/common.tsx
@@ -0,0 +1,102 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useState } from 'react';
+import { act, fireEvent, render } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import OptionList, { OptionListProps } from '../../../lib/components/option-list';
+import createWrapper from '../../../lib/components/test-utils/dom';
+
+export const options: OptionListProps.Option[] = [
+  { value: 'a', label: 'First', description: 'First description' },
+  { value: 'b', label: 'Second' },
+  { value: 'c', label: 'Third' },
+];
+
+export const withDisabled: OptionListProps.Options = [
+  options[0],
+  { ...options[1], disabled: true, disabledReason: 'Not available in this Region' },
+  options[2],
+];
+
+export const groupedOptions: OptionListProps.Options = [
+  {
+    value: 'compute',
+    label: 'Compute',
+    options: [
+      { value: 'ec2', label: 'EC2' },
+      { value: 'lambda', label: 'Lambda' },
+    ],
+  },
+  {
+    value: 'storage',
+    label: 'Storage',
+    options: [
+      { value: 's3', label: 'S3' },
+      { value: 'efs', label: 'EFS', disabled: true },
+    ],
+  },
+];
+
+const leafOptions = (source: OptionListProps.Options) =>
+  source.flatMap(option => (option as OptionListProps.OptionGroup).options ?? [option]);
+
+const byValue = (values: string[], source: OptionListProps.Options) =>
+  values.map(value => leafOptions(source).find(option => option.value === value)!);
+
+export type StatefulProps = Partial<Omit<OptionListProps, 'onChange'>> & {
+  initialSelected?: string[];
+  onChange?: jest.Mock;
+};
+
+// Controlled OptionList that keeps its selection in state and reports the selected values to `onChange`.
+export function Stateful({ initialSelected = [], onChange, ...props }: StatefulProps) {
+  const [selectedOptions, setSelectedOptions] = useState<ReadonlyArray<OptionListProps.Option>>(
+    byValue(initialSelected, props.options ?? options)
+  );
+  return (
+    <OptionList
+      ariaLabel="Goals"
+      options={options}
+      selectionType="single"
+      {...props}
+      selectedOptions={selectedOptions}
+      onChange={event => {
+        onChange?.(event.detail.selectedOptions.map(option => option.value));
+        setSelectedOptions(event.detail.selectedOptions);
+      }}
+    />
+  );
+}
+
+export function renderOptionList(jsx: React.ReactElement) {
+  const { container, rerender } = render(jsx);
+  const wrapper = createWrapper(container).findOptionList()!;
+  // There is no test-utils finder for the listbox element, which receives focus and keyboard events.
+  const listbox = wrapper.find('[role="listbox"]')!.getElement();
+  return { container, rerender, wrapper, listbox };
+}
+
+export type Wrapper = ReturnType<typeof renderOptionList>['wrapper'];
+
+export const clickOption = (wrapper: Wrapper, index: number) =>
+  fireEvent.mouseUp(wrapper.findOptionByIndex(index)!.getElement());
+
+export const pressKey = (listbox: HTMLElement, keyCode: number) => fireEvent.keyDown(listbox, { keyCode });
+
+// Moves real focus, so `document.activeElement` is the listbox, as it is for a user.
+export const focusList = (listbox: HTMLElement) => act(() => listbox.focus());
+
+export const blurList = (listbox: HTMLElement) => act(() => listbox.blur());
+
+// In multi selection, the first group header is the first item, so Home highlights it.
+export const highlightFirstGroupHeader = (listbox: HTMLElement) => {
+  focusList(listbox);
+  pressKey(listbox, KeyCode.home);
+};
+
+export const selectedLabels = (wrapper: Wrapper) =>
+  wrapper.findSelectedOptions().map(option => option.findLabel()!.getElement().textContent);
+
+export const highlightedValue = (wrapper: Wrapper) => wrapper.findHighlightedOption()?.getElement().dataset.value;
diff --git a/src/option-list/__tests__/disabled.test.tsx b/src/option-list/__tests__/disabled.test.tsx
new file mode 100644
index 00000000000..5ae97f4d693
--- /dev/null
+++ b/src/option-list/__tests__/disabled.test.tsx
@@ -0,0 +1,108 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { fireEvent } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import { OptionListProps } from '../../../lib/components/option-list';
+import createWrapper from '../../../lib/components/test-utils/dom';
+import {
+  clickOption,
+  focusList,
+  highlightedValue,
+  options,
+  pressKey,
+  renderOptionList,
+  selectedLabels,
+  Stateful,
+  withDisabled,
+} from './common';
+
+const findTooltip = () => createWrapper().findTooltip();
+
+describe('OptionList disabled options', () => {
+  test.each<OptionListProps.SelectionType>(['single', 'multi'])(
+    'marks disabled options and ignores clicks on them (%s)',
+    selectionType => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(
+        <Stateful selectionType={selectionType} options={withDisabled} onChange={onChange} />
+      );
+      const disabledOption = wrapper.findOptionByValue('b')!;
+      expect(disabledOption.isDisabled()).toBe(true);
+      expect(disabledOption.getElement()).toHaveAttribute('aria-disabled', 'true');
+      expect(wrapper.findOptionByValue('a')!.isDisabled()).toBe(false);
+
+      clickOption(wrapper, 2);
+      expect(onChange).not.toHaveBeenCalled();
+      expect(wrapper.findSelectedOptions()).toHaveLength(0);
+    }
+  );
+
+  test('keyboard can reach a disabled option but Enter does not select it', () => {
+    const onChange = jest.fn();
+    const { wrapper, listbox } = renderOptionList(<Stateful options={withDisabled} onChange={onChange} />);
+    focusList(listbox);
+    pressKey(listbox, KeyCode.down);
+    expect(highlightedValue(wrapper)).toBe('b');
+    pressKey(listbox, KeyCode.enter);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  test('a selected disabled option stays selected and cannot be deselected in multi mode', () => {
+    const onChange = jest.fn();
+    const { wrapper } = renderOptionList(
+      <Stateful selectionType="multi" options={withDisabled} initialSelected={['b']} onChange={onChange} />
+    );
+    clickOption(wrapper, 2);
+    expect(onChange).not.toHaveBeenCalled();
+    expect(selectedLabels(wrapper)).toEqual(['Second']);
+  });
+
+  test('describes the disabled option with its disabled reason', () => {
+    const { wrapper } = renderOptionList(<Stateful options={withDisabled} />);
+    const describedBy = wrapper.findOptionByValue('b')!.getElement().getAttribute('aria-describedby');
+    expect(describedBy).toBeTruthy();
+    expect(document.getElementById(describedBy!)).toHaveTextContent('Not available in this Region');
+  });
+
+  test.each<OptionListProps.SelectionType>(['single', 'multi'])(
+    'does not show the disabled reason tooltip when renderOption is used (%s)',
+    selectionType => {
+      const { wrapper, listbox } = renderOptionList(
+        <Stateful
+          selectionType={selectionType}
+          options={withDisabled}
+          renderOption={({ item }) => <span>Custom {item.option.label}</span>}
+        />
+      );
+      // Custom content owns the visible output, so the tooltip isn't shown.
+      focusList(listbox);
+      pressKey(listbox, KeyCode.down);
+      expect(highlightedValue(wrapper)).toBe('b');
+      expect(findTooltip()).toBeNull();
+    }
+  );
+
+  test('Escape closes the disabled reason tooltip and keeps the highlight and selection', () => {
+    const onChange = jest.fn();
+    const { wrapper, listbox } = renderOptionList(
+      <Stateful
+        options={[options[0], { value: 'b', label: 'Second', disabled: true, disabledReason: <b>Needs a quota</b> }]}
+        initialSelected={['a']}
+        onChange={onChange}
+      />
+    );
+    focusList(listbox);
+    expect(findTooltip()).toBeNull();
+    pressKey(listbox, KeyCode.down);
+    expect(findTooltip()!.findContent()!.getElement()).toHaveTextContent('Needs a quota');
+
+    fireEvent.keyDown(listbox, { key: 'Escape', keyCode: KeyCode.escape });
+    expect(findTooltip()).toBeNull();
+    expect(highlightedValue(wrapper)).toBe('b');
+    expect(onChange).not.toHaveBeenCalled();
+    expect(selectedLabels(wrapper)).toEqual(['First']);
+  });
+});
diff --git a/src/option-list/__tests__/group-state.test.tsx b/src/option-list/__tests__/group-state.test.tsx
new file mode 100644
index 00000000000..fe52234a8a0
--- /dev/null
+++ b/src/option-list/__tests__/group-state.test.tsx
@@ -0,0 +1,165 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React, { useState } from 'react';
+import { fireEvent } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import OptionList, { OptionListProps } from '../../../lib/components/option-list';
+import {
+  clickOption,
+  focusList,
+  groupedOptions,
+  highlightedValue,
+  highlightFirstGroupHeader,
+  pressKey,
+  renderOptionList,
+  Stateful,
+} from './common';
+
+describe('OptionList option groups', () => {
+  test('renders each group labelled by its header, and option finders skip the headers', () => {
+    const { wrapper } = renderOptionList(<Stateful options={groupedOptions} />);
+    expect(wrapper.findGroupHeaders().map(header => header.findLabel()!.getElement().textContent)).toEqual([
+      'Compute',
+      'Storage',
+    ]);
+    const header = wrapper.findGroupHeaderByValue('storage')!.getElement();
+    expect(header.closest('[role="group"]')).toHaveAttribute('aria-labelledby', header.id);
+    expect(wrapper.findOptions().map(option => option.getElement().dataset.value)).toEqual([
+      'ec2',
+      'lambda',
+      's3',
+      'efs',
+    ]);
+    expect(wrapper.findOptionByIndex(3)!.getElement().dataset.value).toBe('s3');
+  });
+
+  test('onChange returns the original options and never a group', () => {
+    const onChange = jest.fn();
+    const { wrapper } = renderOptionList(
+      <OptionList
+        ariaLabel="Services"
+        options={groupedOptions}
+        selectionType="multi"
+        onChange={({ detail }) => onChange(detail.selectedOptions)}
+      />
+    );
+    fireEvent.mouseUp(wrapper.findGroupHeaderByValue('compute')!.getElement());
+    const [ec2, lambda] = (groupedOptions[0] as OptionListProps.OptionGroup).options;
+    expect(onChange.mock.calls[0][0]).toHaveLength(2);
+    expect(onChange.mock.calls[0][0][0]).toBe(ec2);
+    expect(onChange.mock.calls[0][0][1]).toBe(lambda);
+  });
+
+  describe('single selection', () => {
+    test('group headers cannot be chosen and arrow keys skip them', () => {
+      const onChange = jest.fn();
+      const { wrapper, listbox } = renderOptionList(<Stateful options={groupedOptions} onChange={onChange} />);
+      fireEvent.mouseUp(wrapper.findGroupHeaderByValue('compute')!.getElement());
+      expect(onChange).not.toHaveBeenCalled();
+
+      focusList(listbox);
+      expect(highlightedValue(wrapper)).toBe('ec2');
+      pressKey(listbox, KeyCode.down);
+      pressKey(listbox, KeyCode.down);
+      expect(highlightedValue(wrapper)).toBe('s3');
+      pressKey(listbox, KeyCode.home);
+      pressKey(listbox, KeyCode.up);
+      expect(highlightedValue(wrapper)).toBe('efs');
+    });
+
+    test('arrows still wrap when the list starts with a group that has options', () => {
+      const { wrapper, listbox } = renderOptionList(
+        <Stateful
+          options={[
+            { value: 'fruits', label: 'Fruits', options: [{ value: 'apple', label: 'Apple' }] },
+            { value: 'banana', label: 'Banana' },
+          ]}
+        />
+      );
+      focusList(listbox);
+      expect(highlightedValue(wrapper)).toBe('apple');
+      pressKey(listbox, KeyCode.up);
+      expect(highlightedValue(wrapper)).toBe('banana');
+      pressKey(listbox, KeyCode.down);
+      expect(highlightedValue(wrapper)).toBe('apple');
+    });
+  });
+
+  describe('multi selection', () => {
+    test('the group header is checked, mixed or unchecked by its selected options', () => {
+      const { wrapper } = renderOptionList(<Stateful selectionType="multi" options={groupedOptions} />);
+      const header = () => wrapper.findGroupHeaderByValue('compute')!;
+      expect(header().getElement()).toHaveAttribute('aria-checked', 'false');
+      clickOption(wrapper, 1);
+      expect(header().getElement()).toHaveAttribute('aria-checked', 'mixed');
+      expect(header().isSelected()).toBe(false);
+      clickOption(wrapper, 2);
+      expect(header().getElement()).toHaveAttribute('aria-checked', 'true');
+      expect(header().isSelected()).toBe(true);
+    });
+
+    test('choosing a group header toggles its enabled options with the mouse and keyboard', () => {
+      const onChange = jest.fn();
+      const { wrapper, listbox } = renderOptionList(
+        <Stateful selectionType="multi" options={groupedOptions} initialSelected={['efs']} onChange={onChange} />
+      );
+      const storageHeader = wrapper.findGroupHeaderByValue('storage')!.getElement();
+      fireEvent.mouseUp(storageHeader);
+      expect(onChange).toHaveBeenLastCalledWith(['efs', 's3']);
+      fireEvent.mouseUp(storageHeader);
+      expect(onChange).toHaveBeenLastCalledWith(['efs']);
+
+      highlightFirstGroupHeader(listbox);
+      expect(wrapper.findGroupHeaderByValue('compute')!.isHighlighted()).toBe(true);
+      pressKey(listbox, KeyCode.enter);
+      expect(onChange).toHaveBeenLastCalledWith(['efs', 'ec2', 'lambda']);
+      pressKey(listbox, KeyCode.space);
+      expect(onChange).toHaveBeenLastCalledWith(['efs']);
+    });
+
+    test('keeps the highlight when the options are recreated with the same values', () => {
+      // The options are created on every render, so they are new objects after each change.
+      // The highlight is index-based, and this passes because the index doesn't move.
+      // Follow-up: keep the highlight on its option when options are added, removed or reordered.
+      function RebuiltOptions() {
+        const [selectedOptions, setSelectedOptions] = useState<ReadonlyArray<OptionListProps.Option>>([]);
+        return (
+          <OptionList
+            ariaLabel="Services"
+            selectionType="multi"
+            options={[{ value: 'compute', label: 'Compute', options: [{ value: 'ec2', label: 'EC2' }] }]}
+            selectedOptions={selectedOptions}
+            onChange={({ detail }) => setSelectedOptions(detail.selectedOptions)}
+          />
+        );
+      }
+      const { wrapper, listbox } = renderOptionList(<RebuiltOptions />);
+      const header = () => wrapper.findGroupHeaderByValue('compute')!;
+      highlightFirstGroupHeader(listbox);
+      expect(header().isHighlighted()).toBe(true);
+      pressKey(listbox, KeyCode.enter);
+      expect(header().isSelected()).toBe(true);
+      expect(header().isHighlighted()).toBe(true);
+      pressKey(listbox, KeyCode.enter);
+      expect(header().isSelected()).toBe(false);
+    });
+
+    test('a disabled group disables its options', () => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(
+        <Stateful
+          selectionType="multi"
+          options={[{ value: 'db', label: 'Databases', disabled: true, options: [{ value: 'rds', label: 'RDS' }] }]}
+          onChange={onChange}
+        />
+      );
+      expect(wrapper.findGroupHeaderByValue('db')!.isDisabled()).toBe(true);
+      expect(wrapper.findOptionByValue('rds')!.isDisabled()).toBe(true);
+      fireEvent.mouseUp(wrapper.findGroupHeaderByValue('db')!.getElement());
+      clickOption(wrapper, 1);
+      expect(onChange).not.toHaveBeenCalled();
+    });
+  });
+});
diff --git a/src/option-list/__tests__/highlight.test.tsx b/src/option-list/__tests__/highlight.test.tsx
new file mode 100644
index 00000000000..80f8ec1519f
--- /dev/null
+++ b/src/option-list/__tests__/highlight.test.tsx
@@ -0,0 +1,163 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { fireEvent } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import OptionList, { OptionListProps } from '../../../lib/components/option-list';
+import {
+  blurList,
+  clickOption,
+  focusList,
+  highlightedValue,
+  pressKey,
+  renderOptionList,
+  selectedLabels,
+  Stateful,
+  StatefulProps,
+} from './common';
+
+import selectableItemStyles from '../../../lib/components/internal/components/selectable-item/styles.css.js';
+
+// OptionList scrolls the highlighted option into view with `scrollIntoView`, which jsdom doesn't implement.
+const originalScrollIntoView = HTMLElement.prototype.scrollIntoView;
+let scrollIntoView: jest.Mock;
+
+beforeEach(() => {
+  scrollIntoView = HTMLElement.prototype.scrollIntoView = jest.fn();
+});
+afterEach(() => {
+  HTMLElement.prototype.scrollIntoView = originalScrollIntoView;
+});
+
+const lastScrolledValue = () =>
+  (scrollIntoView.mock.instances[scrollIntoView.mock.instances.length - 1] as HTMLElement).dataset.value;
+
+describe('OptionList focus and highlight', () => {
+  const longOptions: OptionListProps.Option[] = [
+    ...Array.from({ length: 9 }, (_, index) => ({ value: `${index}`, label: `Option ${index}` })),
+    { value: 'special', label: 'Special' },
+  ];
+
+  const renderLongList = (props: StatefulProps = {}) => renderOptionList(<Stateful options={longOptions} {...props} />);
+
+  test('does not scroll when a grouped list mounts without a highlight', () => {
+    // Single-selection group headers are not interactive and render with data-mouse-target="-1",
+    // the same index the list reports when nothing is highlighted.
+    const twoGroups: OptionListProps.Options = [
+      { value: 'group-1', label: 'Group 1', options: [{ value: '1', label: 'Option 1' }] },
+      { value: 'group-2', label: 'Group 2', options: [{ value: '2', label: 'Option 2' }] },
+    ];
+    renderOptionList(<Stateful options={twoGroups} />);
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+
+  test('hovering highlights the option without scrolling, and leaving the list clears it', () => {
+    const { wrapper } = renderLongList();
+    fireEvent.mouseMove(wrapper.findOptionByIndex(5)!.getElement());
+    expect(highlightedValue(wrapper)).toBe('4');
+    expect(scrollIntoView).not.toHaveBeenCalled();
+    fireEvent.mouseLeave(wrapper.getElement());
+    expect(wrapper.findHighlightedOption()).toBeNull();
+  });
+
+  test('mouse leave keeps the highlight while the list has focus', () => {
+    const { wrapper, listbox } = renderLongList();
+    focusList(listbox);
+    pressKey(listbox, KeyCode.down);
+    fireEvent.mouseLeave(wrapper.getElement());
+    expect(highlightedValue(wrapper)).toBe('1');
+  });
+
+  test('focus entry highlights and scrolls to the selected option with the keyboard style', () => {
+    const { wrapper, listbox } = renderLongList({ initialSelected: ['special'] });
+    focusList(listbox);
+    const highlighted = wrapper.findHighlightedOption()!;
+    expect(highlighted.getElement().dataset.value).toBe('special');
+    expect(highlighted.getElement()).toHaveClass(selectableItemStyles['is-keyboard']);
+    expect(wrapper.findOptions().filter(option => option.isHighlighted())).toHaveLength(1);
+    expect(listbox).toHaveAttribute('aria-activedescendant', highlighted.getElement().id);
+    expect(scrollIntoView).toHaveBeenCalledTimes(1);
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: 'nearest', inline: 'nearest' });
+    expect(lastScrolledValue()).toBe('special');
+  });
+
+  test('focus entry in multi selection highlights the first option in selection order, not in list order', () => {
+    const { wrapper, listbox } = renderLongList({ selectionType: 'multi', initialSelected: ['5', '2'] });
+    focusList(listbox);
+    expect(highlightedValue(wrapper)).toBe('5');
+    expect(lastScrolledValue()).toBe('5');
+  });
+
+  test('focus entry highlights the first option when nothing is selected', () => {
+    const { wrapper, listbox } = renderLongList();
+    focusList(listbox);
+    expect(highlightedValue(wrapper)).toBe('0');
+    expect(lastScrolledValue()).toBe('0');
+  });
+
+  test('focus entry highlights the first option when the selected option is not in the options', () => {
+    const { wrapper, listbox } = renderOptionList(
+      <OptionList
+        ariaLabel="Goals"
+        options={longOptions}
+        selectionType="single"
+        selectedOptions={[{ value: 'missing' }]}
+        onChange={() => {}}
+      />
+    );
+    focusList(listbox);
+    expect(highlightedValue(wrapper)).toBe('0');
+    expect(lastScrolledValue()).toBe('0');
+  });
+
+  test('focus keeps a hover highlight, so a click selects the hovered option', () => {
+    const { wrapper, listbox } = renderLongList({ initialSelected: ['special'] });
+    // Hover while the list isn't focused, and keep the pointer over the list.
+    fireEvent.mouseMove(wrapper.findOptionByIndex(5)!.getElement());
+    focusList(listbox);
+    // The hover highlight stays, instead of moving to the selected option.
+    expect(highlightedValue(wrapper)).toBe('4');
+    expect(scrollIntoView).not.toHaveBeenCalled();
+    clickOption(wrapper, 5);
+    expect(selectedLabels(wrapper)).toEqual(['Option 4']);
+  });
+
+  test('blur clears the highlight and aria-activedescendant, and the next focus highlights the selected option', () => {
+    const { wrapper, listbox } = renderLongList();
+    expect(listbox).not.toHaveAttribute('aria-activedescendant');
+    focusList(listbox);
+    expect(listbox).toHaveAttribute('aria-activedescendant', wrapper.findOptionByIndex(1)!.getElement().id);
+    clickOption(wrapper, 10);
+    expect(selectedLabels(wrapper)).toEqual(['Special']);
+    blurList(listbox);
+    expect(wrapper.findHighlightedOption()).toBeNull();
+    expect(listbox).not.toHaveAttribute('aria-activedescendant');
+    scrollIntoView.mockClear();
+    focusList(listbox);
+    expect(highlightedValue(wrapper)).toBe('special');
+    expect(lastScrolledValue()).toBe('special');
+  });
+
+  test('keyboard moves scroll the highlighted option into view', () => {
+    const { listbox } = renderLongList();
+    focusList(listbox);
+    scrollIntoView.mockClear();
+    const scrolledValues = [KeyCode.down, KeyCode.end, KeyCode.home, KeyCode.up].map(keyCode => {
+      pressKey(listbox, keyCode);
+      return lastScrolledValue();
+    });
+    expect(scrolledValues).toEqual(['1', 'special', '0', 'special']);
+  });
+
+  test('hovering after keyboard navigation does not scroll', () => {
+    const { wrapper, listbox } = renderLongList();
+    focusList(listbox);
+    scrollIntoView.mockClear();
+    fireEvent.mouseMove(wrapper.findOptionByIndex(1)!.getElement());
+    fireEvent.mouseMove(wrapper.findOptionByIndex(5)!.getElement());
+    expect(highlightedValue(wrapper)).toBe('4');
+    expect(scrollIntoView).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/option-list/__tests__/i18n.test.tsx b/src/option-list/__tests__/i18n.test.tsx
new file mode 100644
index 00000000000..f5d2404f296
--- /dev/null
+++ b/src/option-list/__tests__/i18n.test.tsx
@@ -0,0 +1,32 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import TestI18nProvider from '../../../lib/components/i18n/testing';
+import { focusList, renderOptionList, Stateful } from './common';
+
+describe('OptionList i18n', () => {
+  const messages = { 'option-list': { 'i18nStrings.selectedAriaLabel': 'Custom selected' } };
+
+  test('announces the selected option with the provider message', () => {
+    const { wrapper, listbox } = renderOptionList(
+      <TestI18nProvider messages={messages}>
+        <Stateful initialSelected={['a']} />
+      </TestI18nProvider>
+    );
+    focusList(listbox);
+    expect(wrapper.findOptionByValue('a')!.getElement()).toHaveTextContent('Custom selected');
+  });
+
+  test('i18nStrings.selectedAriaLabel takes precedence over the provider message', () => {
+    const { wrapper, listbox } = renderOptionList(
+      <TestI18nProvider messages={messages}>
+        <Stateful initialSelected={['a']} i18nStrings={{ selectedAriaLabel: 'Picked' }} />
+      </TestI18nProvider>
+    );
+    focusList(listbox);
+    const option = wrapper.findOptionByValue('a')!.getElement();
+    expect(option).toHaveTextContent('Picked');
+    expect(option).not.toHaveTextContent('Custom selected');
+  });
+});
diff --git a/src/option-list/__tests__/keyboard.test.tsx b/src/option-list/__tests__/keyboard.test.tsx
new file mode 100644
index 00000000000..7f2dc94f957
--- /dev/null
+++ b/src/option-list/__tests__/keyboard.test.tsx
@@ -0,0 +1,108 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { act, fireEvent } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import {
+  focusList,
+  groupedOptions,
+  highlightedValue,
+  pressKey,
+  renderOptionList,
+  Stateful,
+  withDisabled,
+} from './common';
+
+const typeKey = (listbox: HTMLElement, key: string) => fireEvent.keyDown(listbox, { key });
+
+describe('OptionList keyboard', () => {
+  test('focus highlights the first option, arrows move with wrap-around, Home and End jump', () => {
+    const { wrapper, listbox } = renderOptionList(<Stateful />);
+    const optionId = (index: number) => wrapper.findOptionByIndex(index)!.getElement().id;
+
+    focusList(listbox);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(1));
+
+    pressKey(listbox, KeyCode.down);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(2));
+
+    pressKey(listbox, KeyCode.up);
+    pressKey(listbox, KeyCode.up);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(3));
+
+    pressKey(listbox, KeyCode.down);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(1));
+
+    pressKey(listbox, KeyCode.end);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(3));
+
+    pressKey(listbox, KeyCode.home);
+    expect(listbox).toHaveAttribute('aria-activedescendant', optionId(1));
+  });
+
+  test('Enter and Space select the highlighted option', () => {
+    const onChange = jest.fn();
+    const { listbox } = renderOptionList(<Stateful selectionType="multi" onChange={onChange} />);
+    focusList(listbox);
+
+    pressKey(listbox, KeyCode.enter);
+    expect(onChange).toHaveBeenLastCalledWith(['a']);
+
+    pressKey(listbox, KeyCode.down);
+    pressKey(listbox, KeyCode.space);
+    expect(onChange).toHaveBeenLastCalledWith(['a', 'b']);
+
+    pressKey(listbox, KeyCode.space);
+    expect(onChange).toHaveBeenLastCalledWith(['a']);
+  });
+
+  test('Escape is not handled and reaches the parent', () => {
+    const onChange = jest.fn();
+    const onParentKeyDown = jest.fn();
+    const { listbox } = renderOptionList(
+      <div onKeyDown={event => onParentKeyDown(event.keyCode)}>
+        <Stateful onChange={onChange} />
+      </div>
+    );
+    focusList(listbox);
+    pressKey(listbox, KeyCode.escape);
+    expect(onParentKeyDown).toHaveBeenCalledWith(KeyCode.escape);
+    expect(onChange).not.toHaveBeenCalled();
+  });
+
+  describe('type-ahead', () => {
+    test('typing a character highlights the first option that starts with it', () => {
+      const { wrapper, listbox } = renderOptionList(<Stateful />);
+      focusList(listbox);
+      typeKey(listbox, 't');
+      expect(highlightedValue(wrapper)).toBe('c');
+      expect(listbox).toHaveAttribute('aria-activedescendant', wrapper.findOptionByValue('c')!.getElement().id);
+    });
+
+    test('typing does not highlight a disabled option', () => {
+      jest.useFakeTimers();
+      try {
+        const { wrapper, listbox } = renderOptionList(<Stateful options={withDisabled} />);
+        focusList(listbox);
+        // Only the disabled "Second" starts with "s", so the highlight stays on the first option.
+        typeKey(listbox, 's');
+        expect(highlightedValue(wrapper)).toBe('a');
+        // After the type-ahead resets, an enabled match is still highlighted.
+        act(() => jest.advanceTimersByTime(1000));
+        typeKey(listbox, 't');
+        expect(highlightedValue(wrapper)).toBe('c');
+      } finally {
+        jest.useRealTimers();
+      }
+    });
+
+    test('multi: typing can highlight a group header', () => {
+      const { wrapper, listbox } = renderOptionList(<Stateful selectionType="multi" options={groupedOptions} />);
+      focusList(listbox);
+      typeKey(listbox, 's');
+      expect(wrapper.findGroupHeaderByValue('storage')!.isHighlighted()).toBe(true);
+    });
+  });
+});
diff --git a/src/option-list/__tests__/option-list-a11y.test.tsx b/src/option-list/__tests__/option-list-a11y.test.tsx
new file mode 100644
index 00000000000..9bea2e32979
--- /dev/null
+++ b/src/option-list/__tests__/option-list-a11y.test.tsx
@@ -0,0 +1,97 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { render } from '@testing-library/react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import '../../__a11y__/to-validate-a11y';
+import { OptionListProps } from '../../../lib/components/option-list';
+import {
+  focusList,
+  groupedOptions,
+  highlightedValue,
+  highlightFirstGroupHeader,
+  pressKey,
+  renderOptionList,
+  Stateful,
+  withDisabled,
+  Wrapper,
+} from './common';
+
+import selectableItemStyles from '../../../lib/components/internal/components/selectable-item/styles.selectors.js';
+
+describe('OptionList a11y', () => {
+  test.each<[string, OptionListProps.SelectionType, OptionListProps.Options, string]>([
+    ['single selection', 'single', withDisabled, 'a'],
+    ['multi selection', 'multi', withDisabled, 'a'],
+    ['single selection with groups', 'single', groupedOptions, 'ec2'],
+    ['multi selection with groups', 'multi', groupedOptions, 'ec2'],
+  ])('is accessible: %s', async (_, selectionType, source, selected) => {
+    const { container } = render(
+      <Stateful selectionType={selectionType} options={source} initialSelected={[selected]} />
+    );
+    await expect(container).toValidateA11y();
+  });
+
+  test('is accessible while an option is highlighted', async () => {
+    const { container, listbox } = renderOptionList(<Stateful selectionType="multi" options={groupedOptions} />);
+    focusList(listbox);
+    pressKey(listbox, KeyCode.down);
+    expect(listbox).toHaveAttribute('aria-activedescendant');
+    await expect(container).toValidateA11y();
+  });
+
+  // The visible content of the highlighted option is hidden from screen readers, so only this text is announced.
+  const announcement = (wrapper: Wrapper) =>
+    wrapper.findHighlightedOption()!.find(`.${selectableItemStyles['screenreader-content']}`)!.getElement().textContent;
+
+  test('announces the group of the highlighted option by default', () => {
+    const { wrapper, listbox } = renderOptionList(<Stateful options={groupedOptions} />);
+    focusList(listbox);
+    expect(highlightedValue(wrapper)).toBe('ec2');
+    expect(announcement(wrapper)).toContain('Compute');
+  });
+
+  describe('renderHighlightedAriaLive', () => {
+    test('announces the highlighted option with the custom text, for example with custom option content', () => {
+      const { wrapper, listbox } = renderOptionList(
+        <Stateful
+          options={[{ value: 'a' }, { value: 'b' }]}
+          renderOption={({ item }) => <span>{item.option.value === 'a' ? 'Production' : 'Staging'}</span>}
+          renderHighlightedAriaLive={option => (option.value === 'a' ? 'Production' : 'Staging')}
+        />
+      );
+      focusList(listbox);
+      expect(announcement(wrapper)).toBe('Production');
+      pressKey(listbox, KeyCode.down);
+      expect(announcement(wrapper)).toBe('Staging');
+    });
+
+    test('receives the consumer option objects and the group when it changes', () => {
+      const renderHighlightedAriaLive = jest.fn(() => 'announcement');
+      const [compute] = groupedOptions as OptionListProps.OptionGroup[];
+      const { listbox } = renderOptionList(
+        <Stateful options={groupedOptions} renderHighlightedAriaLive={renderHighlightedAriaLive} />
+      );
+      focusList(listbox);
+      expect(renderHighlightedAriaLive).toHaveBeenLastCalledWith(compute.options[0], compute);
+    });
+
+    test('receives the consumer group object when a group header is highlighted in multi selection', () => {
+      const renderHighlightedAriaLive = jest.fn(() => 'announcement');
+      const [compute] = groupedOptions as OptionListProps.OptionGroup[];
+      const { listbox } = renderOptionList(
+        <Stateful
+          selectionType="multi"
+          options={groupedOptions}
+          renderHighlightedAriaLive={renderHighlightedAriaLive}
+        />
+      );
+      highlightFirstGroupHeader(listbox);
+      const calls = renderHighlightedAriaLive.mock
+        .calls as unknown as Parameters<OptionListProps.ContainingOptionAndGroupString>[];
+      expect(calls[calls.length - 1][0]).toBe(compute);
+    });
+  });
+});
diff --git a/src/option-list/__tests__/option-list.test.tsx b/src/option-list/__tests__/option-list.test.tsx
new file mode 100644
index 00000000000..4f21d81caa5
--- /dev/null
+++ b/src/option-list/__tests__/option-list.test.tsx
@@ -0,0 +1,297 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+import { act, render } from '@testing-library/react';
+
+import { warnOnce } from '@cloudscape-design/component-toolkit/internal';
+
+import OptionList, { OptionListProps } from '../../../lib/components/option-list';
+import createWrapper from '../../../lib/components/test-utils/dom';
+import { clickOption, groupedOptions, options, renderOptionList, selectedLabels, Stateful } from './common';
+
+import styles from '../../../lib/components/internal/components/option/styles.selectors.js';
+
+jest.mock('@cloudscape-design/component-toolkit/internal', () => ({
+  ...jest.requireActual('@cloudscape-design/component-toolkit/internal'),
+  warnOnce: jest.fn(),
+}));
+
+afterEach(() => {
+  (warnOnce as jest.Mock).mockReset();
+});
+
+describe('OptionList', () => {
+  describe('rendering', () => {
+    test('renders a labelled, focusable listbox with an option per item', () => {
+      const { wrapper, listbox } = renderOptionList(<Stateful />);
+      expect(listbox).toHaveAttribute('aria-label', 'Goals');
+      expect(listbox).toHaveAttribute('tabindex', '0');
+      expect(wrapper.findOptions().map(option => option.getElement().getAttribute('role'))).toEqual([
+        'option',
+        'option',
+        'option',
+      ]);
+    });
+
+    test('renders label and description', () => {
+      const { wrapper } = renderOptionList(<Stateful />);
+      const first = wrapper.findOptionByValue('a')!;
+      expect(first.findLabel()!.getElement()).toHaveTextContent('First');
+      expect(first.findDescription()!.getElement()).toHaveTextContent('First description');
+      expect(wrapper.findOptionByValue('b')!.findDescription()).toBeNull();
+    });
+
+    test('renders icon, label tag and tags', () => {
+      const { wrapper } = renderOptionList(
+        <Stateful
+          options={[
+            {
+              value: 'a',
+              label: 'First',
+              icon: <span data-testid="custom-icon" />,
+              labelTag: '128 GB',
+              tags: ['CPU-v2', '2 GB RAM'],
+            },
+          ]}
+        />
+      );
+      const option = wrapper.findOptionByValue('a')!;
+      // The icon slot spaces the icon from the content.
+      expect(option.find('[data-testid="custom-icon"]')!.getElement().parentElement).toHaveClass(styles.icon);
+      expect(option.findLabelTag()!.getElement()).toHaveTextContent('128 GB');
+      expect(option.findTags().map(tag => tag.getElement().textContent)).toEqual(['CPU-v2', '2 GB RAM']);
+    });
+
+    test('renders no icon slot when the option has no icon', () => {
+      const { wrapper } = renderOptionList(<Stateful />);
+      expect(wrapper.findOptionByValue('a')!.find(`.${styles.icon}`)).toBeNull();
+    });
+
+    test('passes aria-labelledby and aria-describedby to the listbox', () => {
+      const { listbox } = renderOptionList(
+        <Stateful ariaLabel={undefined} ariaLabelledby="heading" ariaDescribedby="description" />
+      );
+      expect(listbox).toHaveAttribute('aria-labelledby', 'heading');
+      expect(listbox).toHaveAttribute('aria-describedby', 'description');
+    });
+
+    test('renders an empty listbox when there are no options', () => {
+      const { wrapper } = renderOptionList(<Stateful options={[]} />);
+      expect(wrapper.findOptions()).toHaveLength(0);
+    });
+
+    test('warns about duplicate values', () => {
+      renderOptionList(
+        <Stateful
+          options={[
+            { value: 'same', label: 'A' },
+            { value: 'same', label: 'B' },
+          ]}
+        />
+      );
+      expect(warnOnce).toHaveBeenCalledWith(
+        'OptionList',
+        'Every option must have a unique `value`. The component may work incorrectly.'
+      );
+    });
+
+    test('warns about duplicate group values, but not when a group shares a value with an option', () => {
+      const groupWarning = 'Every option group must have a unique `value`. The component may work incorrectly.';
+      renderOptionList(
+        <Stateful options={[{ value: 'same', label: 'Group', options: [{ value: 'same', label: 'Option' }] }]} />
+      );
+      expect(warnOnce).not.toHaveBeenCalledWith('OptionList', groupWarning);
+      renderOptionList(
+        <Stateful
+          options={[
+            { value: 'same', label: 'A', options: [{ value: 'a', label: 'Option A' }] },
+            { value: 'same', label: 'B', options: [{ value: 'b', label: 'Option B' }] },
+          ]}
+        />
+      );
+      expect(warnOnce).toHaveBeenCalledWith('OptionList', groupWarning);
+    });
+
+    test('warns about an option without a value inside a group, but not about valid groups', () => {
+      const valueWarning =
+        'You provided an `options` prop where at least one non-group array element is missing the `value` field. This field is required for all options without sub-items.';
+      renderOptionList(<Stateful options={groupedOptions} />);
+      expect(warnOnce).not.toHaveBeenCalledWith('OptionList', valueWarning);
+      renderOptionList(
+        <Stateful
+          options={[{ value: 'group', label: 'Group', options: [{ label: 'No value' } as OptionListProps.Option] }]}
+        />
+      );
+      expect(warnOnce).toHaveBeenCalledWith('OptionList', valueWarning);
+    });
+
+    test('passes id, className and data attributes to the root', () => {
+      const { container } = render(
+        <OptionList
+          id="my-list"
+          className="custom"
+          data-testid="root"
+          ariaLabel="Goals"
+          options={options}
+          selectionType="single"
+        />
+      );
+      const root = createWrapper(container).findOptionList()!.getElement();
+      expect(root).toHaveAttribute('id', 'my-list');
+      expect(root).toHaveClass('custom');
+      expect(root).toHaveAttribute('data-testid', 'root');
+    });
+  });
+
+  describe('selection', () => {
+    test('single: marks only the selected option with aria-selected and a check mark', () => {
+      const { wrapper, listbox } = renderOptionList(<Stateful initialSelected={['b']} />);
+      expect(wrapper.findOptions().map(option => option.getElement().getAttribute('aria-selected'))).toEqual([
+        'false',
+        'true',
+        'false',
+      ]);
+      expect(selectedLabels(wrapper)).toEqual(['Second']);
+      expect(listbox).not.toHaveAttribute('aria-multiselectable');
+    });
+
+    test('single: clicking replaces the selection and repeat click keeps it selected', () => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(<Stateful onChange={onChange} />);
+
+      clickOption(wrapper, 2);
+      expect(onChange).toHaveBeenLastCalledWith(['b']);
+
+      clickOption(wrapper, 3);
+      expect(onChange).toHaveBeenLastCalledWith(['c']);
+
+      clickOption(wrapper, 3);
+      expect(onChange).toHaveBeenCalledTimes(3);
+      expect(onChange).toHaveBeenLastCalledWith(['c']);
+      expect(selectedLabels(wrapper)).toEqual(['Third']);
+    });
+
+    test('single: uses only the first entry of selectedOptions', () => {
+      const { wrapper } = renderOptionList(
+        <OptionList
+          ariaLabel="Goals"
+          options={options}
+          selectionType="single"
+          selectedOptions={[{ value: 'b' }, { value: 'c' }]}
+          onChange={() => {}}
+        />
+      );
+      expect(selectedLabels(wrapper)).toEqual(['Second']);
+    });
+
+    test('onChange returns the original option objects', () => {
+      const onChange = jest.fn();
+      const optionsWithIcon = [{ ...options[0], icon: <span /> }, ...options.slice(1)];
+      const { wrapper } = renderOptionList(
+        <OptionList
+          ariaLabel="Goals"
+          options={optionsWithIcon}
+          selectionType="single"
+          onChange={({ detail }) => onChange(detail)}
+        />
+      );
+      clickOption(wrapper, 1);
+      expect(onChange.mock.calls[0][0].selectedOptions[0]).toBe(optionsWithIcon[0]);
+    });
+
+    test('multi: marks the listbox multiselectable and every selected option', () => {
+      const { wrapper, listbox } = renderOptionList(<Stateful selectionType="multi" initialSelected={['a', 'c']} />);
+      expect(listbox).toHaveAttribute('aria-multiselectable', 'true');
+      expect(wrapper.findOptions().map(option => option.getElement().getAttribute('aria-selected'))).toEqual([
+        'true',
+        'false',
+        'true',
+      ]);
+      expect(selectedLabels(wrapper)).toEqual(['First', 'Third']);
+    });
+
+    test('multi: clicking toggles options and keeps the selection order', () => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(
+        <Stateful selectionType="multi" initialSelected={['c']} onChange={onChange} />
+      );
+
+      clickOption(wrapper, 1);
+      expect(onChange).toHaveBeenLastCalledWith(['c', 'a']);
+
+      clickOption(wrapper, 3);
+      expect(onChange).toHaveBeenLastCalledWith(['a']);
+      expect(selectedLabels(wrapper)).toEqual(['First']);
+    });
+
+    test('controlled: does not change the selection without the consumer updating selectedOptions', () => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(
+        <OptionList
+          ariaLabel="Goals"
+          options={options}
+          selectionType="single"
+          selectedOptions={[options[0]]}
+          onChange={({ detail }) => onChange(detail.selectedOptions.map(option => option.value))}
+        />
+      );
+      clickOption(wrapper, 2);
+      expect(onChange).toHaveBeenCalledWith(['b']);
+      expect(selectedLabels(wrapper)).toEqual(['First']);
+    });
+
+    test('controlled: warns when selectedOptions is set without onChange', () => {
+      renderOptionList(<OptionList ariaLabel="Goals" options={options} selectionType="single" selectedOptions={[]} />);
+      expect(warnOnce).toHaveBeenCalledWith(
+        'OptionList',
+        'You provided a `selectedOptions` prop without an `onChange` handler. This will render a non-interactive component.'
+      );
+    });
+
+    test('controlled: matches selected options by value, not by reference', () => {
+      const props = { ariaLabel: 'Goals', options, selectionType: 'single' as const, onChange: () => {} };
+      const { wrapper, rerender } = renderOptionList(<OptionList {...props} selectedOptions={[{ value: 'a' }]} />);
+      expect(selectedLabels(wrapper)).toEqual(['First']);
+      rerender(<OptionList {...props} selectedOptions={[{ value: 'c' }]} />);
+      expect(selectedLabels(wrapper)).toEqual(['Third']);
+    });
+
+    test('ignores selected options that do not match an option', () => {
+      const { wrapper } = renderOptionList(
+        <OptionList
+          ariaLabel="Goals"
+          options={options}
+          selectionType="multi"
+          selectedOptions={[{ value: 'missing' }, { value: 'b' }]}
+          onChange={() => {}}
+        />
+      );
+      expect(selectedLabels(wrapper)).toEqual(['Second']);
+    });
+
+    test('uncontrolled: manages selection internally and fires onChange', () => {
+      const onChange = jest.fn();
+      const { wrapper } = renderOptionList(
+        <OptionList
+          ariaLabel="Goals"
+          options={options}
+          selectionType="multi"
+          onChange={({ detail }) => onChange(detail.selectedOptions.map(option => option.value))}
+        />
+      );
+      clickOption(wrapper, 1);
+      clickOption(wrapper, 2);
+      expect(onChange).toHaveBeenLastCalledWith(['a', 'b']);
+      expect(selectedLabels(wrapper)).toEqual(['First', 'Second']);
+    });
+  });
+
+  test('ref.focus() focuses the listbox', () => {
+    const ref = React.createRef<OptionListProps.Ref>();
+    const { listbox } = renderOptionList(
+      <OptionList ref={ref} ariaLabel="Goals" options={options} selectionType="single" />
+    );
+    act(() => ref.current!.focus());
+    expect(document.activeElement).toBe(listbox);
+  });
+});
diff --git a/src/option-list/__tests__/render-option.test.tsx b/src/option-list/__tests__/render-option.test.tsx
new file mode 100644
index 00000000000..1c428a8d7e4
--- /dev/null
+++ b/src/option-list/__tests__/render-option.test.tsx
@@ -0,0 +1,103 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import React from 'react';
+
+import { KeyCode } from '@cloudscape-design/component-toolkit/internal';
+
+import { OptionListProps } from '../../../lib/components/option-list';
+import { groupedOptions, highlightFirstGroupHeader, pressKey, renderOptionList, Stateful } from './common';
+
+describe('OptionList renderOption', () => {
+  test('renders custom content for options and group headers with the original options', () => {
+    const renderOption = jest.fn(({ item }: Parameters<OptionListProps['renderOption'] & {}>[0]) => (
+      <span>{`${item.type}: ${item.option.label}`}</span>
+    ));
+    const { wrapper } = renderOptionList(
+      <Stateful options={groupedOptions} initialSelected={['ec2']} renderOption={renderOption} />
+    );
+    expect(wrapper.findOptionByValue('ec2')!.getElement()).toHaveTextContent('item: EC2');
+    expect(wrapper.findGroupHeaderByValue('compute')!.getElement()).toHaveTextContent('group: Compute');
+
+    const [compute] = groupedOptions as OptionListProps.OptionGroup[];
+    const items = renderOption.mock.calls.map(([{ item }]) => item);
+    expect(items).toContainEqual({ type: 'group', index: 0, option: compute, disabled: false });
+    expect(items).toContainEqual({
+      type: 'item',
+      index: 1,
+      option: compute.options[0],
+      selected: true,
+      highlighted: false,
+      disabled: false,
+      parent: { type: 'group', index: 0, option: compute, disabled: false },
+    });
+    expect(items.find(item => item.option === compute.options[0])!.option).toBe(compute.options[0]);
+
+    // Single selection leaves out the multi-selection group state, on group headers and on `parent`.
+    const groupItems = [
+      ...items.filter(item => item.type === 'group'),
+      ...items.flatMap(item => (item.type === 'item' && item.parent ? [item.parent] : [])),
+    ];
+    expect(groupItems.length).toBeGreaterThan(0);
+    for (const group of groupItems) {
+      expect(group).not.toHaveProperty('selected');
+      expect(group).not.toHaveProperty('indeterminate');
+      expect(group).not.toHaveProperty('highlighted');
+    }
+  });
+
+  test('multi: items carry the option icon', () => {
+    const icon = <span data-testid="custom-icon" />;
+    const optionIcons: React.ReactNode[] = [];
+    const renderOption = ({ item }: { item: OptionListProps.Item }) => {
+      if (item.type === 'item') {
+        optionIcons.push(item.option.icon);
+      }
+      return null;
+    };
+    renderOptionList(
+      <Stateful
+        selectionType="multi"
+        options={[{ value: 'compute', label: 'Compute', options: [{ value: 'ec2', label: 'EC2', icon }] }]}
+        renderOption={renderOption}
+      />
+    );
+    expect(optionIcons).toContain(icon);
+  });
+
+  test('multi: group header items carry the group and its checkbox and highlight state', () => {
+    const computeOptions: OptionListProps.Options = [
+      {
+        value: 'compute',
+        label: 'Compute',
+        options: [
+          { value: 'ec2', label: 'EC2' },
+          { value: 'lambda', label: 'Lambda' },
+        ],
+      },
+    ];
+    const groupStates: Array<Pick<OptionListProps.OptionGroupItem, 'selected' | 'indeterminate' | 'highlighted'>> = [];
+    const renderOption = jest.fn(({ item }: { item: OptionListProps.Item }) => {
+      if (item.type === 'group') {
+        groupStates.push({
+          selected: item.selected,
+          indeterminate: item.indeterminate,
+          highlighted: item.highlighted,
+        });
+      }
+      return null;
+    });
+    const { listbox } = renderOptionList(
+      <Stateful selectionType="multi" options={computeOptions} initialSelected={['ec2']} renderOption={renderOption} />
+    );
+    expect(renderOption).toHaveBeenCalledWith(
+      expect.objectContaining({ item: expect.objectContaining({ type: 'group', option: computeOptions[0] }) })
+    );
+    expect(groupStates[groupStates.length - 1]).toEqual({ selected: false, indeterminate: true, highlighted: false });
+
+    highlightFirstGroupHeader(listbox);
+    expect(groupStates[groupStates.length - 1]).toEqual({ selected: false, indeterminate: true, highlighted: true });
+
+    pressKey(listbox, KeyCode.enter);
+    expect(groupStates[groupStates.length - 1]).toEqual({ selected: true, indeterminate: false, highlighted: true });
+  });
+});

From 3dcfa937b1b1fabce34ff7bdf7a8708d403ad7cb Mon Sep 17 00:00:00 2001
From: Amanuel Sisay <amanabiy@amazon.de>
Date: Wed, 4 Nov 2026 14:30:46 +0100
Subject: [PATCH 5/5] chore: clean up translations

---
 src/i18n/messages/all.ar.json    | 3 ---
 src/i18n/messages/all.pt-BR.json | 2 +-
 src/i18n/messages/all.th.json    | 3 ---
 src/i18n/messages/all.tr.json    | 2 +-
 src/i18n/messages/all.zh-CN.json | 2 +-
 5 files changed, 3 insertions(+), 9 deletions(-)

diff --git a/src/i18n/messages/all.ar.json b/src/i18n/messages/all.ar.json
index dfcdab61ae3..a97ca523c51 100644
--- a/src/i18n/messages/all.ar.json
+++ b/src/i18n/messages/all.ar.json
@@ -255,9 +255,6 @@
     "deselectAriaLabel": "إزالة {option__label}",
     "i18nStrings.selectAllText": "حدد الكل"
   },
-  "option-list": {
-    "i18nStrings.selectedAriaLabel": "مُحدَّد"
-  },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "الانتقال إلى الصفحة",
     "ariaLabels.nextPageLabel": "الصفحة التالية",
diff --git a/src/i18n/messages/all.pt-BR.json b/src/i18n/messages/all.pt-BR.json
index 0f2b9ba76b0..b2ff7904a07 100644
--- a/src/i18n/messages/all.pt-BR.json
+++ b/src/i18n/messages/all.pt-BR.json
@@ -281,7 +281,7 @@
     "i18nStrings.selectAllText": "Selecionar tudo"
   },
   "option-list": {
-    "i18nStrings.selectedAriaLabel": "Selecionado"
+    "i18nStrings.selectedAriaLabel": "Selecionados"
   },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Ir para a página",
diff --git a/src/i18n/messages/all.th.json b/src/i18n/messages/all.th.json
index eaae619910b..f1a11920b08 100644
--- a/src/i18n/messages/all.th.json
+++ b/src/i18n/messages/all.th.json
@@ -160,9 +160,6 @@
   "multiselect": {
     "deselectAriaLabel": "ลบ {option__label}"
   },
-  "option-list": {
-    "i18nStrings.selectedAriaLabel": "เลือกไว้"
-  },
   "pagination": {
     "ariaLabels.nextPageLabel": "หน้าถัดไป",
     "ariaLabels.pageLabel": "หน้า {pageNumber} จากทุกหน้า",
diff --git a/src/i18n/messages/all.tr.json b/src/i18n/messages/all.tr.json
index 7c088f10343..07371331c5d 100644
--- a/src/i18n/messages/all.tr.json
+++ b/src/i18n/messages/all.tr.json
@@ -281,7 +281,7 @@
     "i18nStrings.selectAllText": "Tümünü seç"
   },
   "option-list": {
-    "i18nStrings.selectedAriaLabel": "Seçili"
+    "i18nStrings.selectedAriaLabel": "Seçildi"
   },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "Sayfaya atla",
diff --git a/src/i18n/messages/all.zh-CN.json b/src/i18n/messages/all.zh-CN.json
index 22863cfb15a..4825a75aad2 100644
--- a/src/i18n/messages/all.zh-CN.json
+++ b/src/i18n/messages/all.zh-CN.json
@@ -281,7 +281,7 @@
     "i18nStrings.selectAllText": "选择全部"
   },
   "option-list": {
-    "i18nStrings.selectedAriaLabel": "已选定"
+    "i18nStrings.selectedAriaLabel": "已选中"
   },
   "pagination": {
     "ariaLabels.jumpToPageButtonLabel": "跳转到页面",