amanabiy · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026 · Nov 4, 2026
@@ -59,6 +59,7 @@ const pluralizationMap = {
   Modal: 'Modals',
   Multiselect: 'Multiselects',
   NavigableGroup: 'NavigableGroups',
+  OptionList: 'OptionLists',
   Pagination: 'Paginations',
   AppLayoutToolbar: 'AppLayoutToolbars',
   PanelLayout: 'PanelLayouts',

@@ -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>
+  );
+}
@@ -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} />;
+}
@@ -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} />;
+}
@@ -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>
+  );
+}
@@ -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;
+}