Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat: XDSMultiSelector — multi-select dropdown (#1008) (#1013)

Cindy Zhange12a6fce991e
diff --git a/.claude/commands/create-component.md b/.claude/commands/create-component.md
index 49d6737d9b..6b1c597972 100644
--- a/.claude/commands/create-component.md
+++ b/.claude/commands/create-component.md
@@ -1,6 +1,6 @@
# Create XDS Component
-Create a new XDS component following established patterns.
+Create a new XDS component following the established protocols.
## Component Name
@@ -8,177 +8,31 @@ $ARGUMENTS
## Instructions
-Create a new component in `/packages/core/src/{ComponentName}/` with the following files:
-
-### 1. {ComponentName}.tsx (Main Component)
-
-Use this structure based on Button.tsx:
-
-```tsx
-/**
- * @file {ComponentName}.tsx
- * @input Uses React forwardRef, HTMLAttributes, ReactNode
- * @output Exports {ComponentName} component, {ComponentName}Props, {ComponentName}Variant types
- * @position Core implementation
- *
- * SYNC: When modified, update these files to stay in sync:
- * - /packages/core/src/{ComponentName}/{ComponentName}.doc.mjs
- * - /packages/core/src/{ComponentName}/{ComponentName}.test.tsx
- * - /packages/core/src/{ComponentName}/index.ts
- * - /apps/storybook/stories/{ComponentName}.stories.tsx
- */
-
-import { forwardRef, useContext, type HTMLAttributes, type ReactNode } from 'react';
-import * as stylex from '@stylexjs/stylex';
-import {
- colorTokens,
- spacingTokens,
- radiusTokens,
- transitionTokens,
- typographyTokens,
-} from '../theme/tokens.stylex';
-import { ThemeContext } from '../theme/ThemeContext';
-import type { StyleXStyles } from '../theme/types';
-
-// Define styles first
-const styles = stylex.create({
- base: {
- // Base styles using tokens
- },
- disabled: {
- cursor: 'not-allowed',
- opacity: 0.5,
- },
-});
-
-// Define variants - {ComponentName}Variant type will be derived from this
-const variants = stylex.create({
- default: {
- // Variant styles using tokens
- },
-});
-
-// Derive variant type from the variants object
-export type {ComponentName}Variant = keyof typeof variants;
-
-// =============================================================================
-// Module Augmentation - Register variant type with ComponentStyles
-// =============================================================================
-// This allows themes to provide type-safe variant overrides for this component
-
-declare module '../theme/types' {
- interface ComponentStyles {
- {componentName}?: {
- variants?: Partial<Record<{ComponentName}Variant, StyleXStyles>>;
- };
- }
-}
-
-export interface {ComponentName}Props extends HTMLAttributes<HTMLElement> {
- variant?: {ComponentName}Variant;
- children: ReactNode;
-}
-
-export const {ComponentName} = forwardRef<HTMLElement, {ComponentName}Props>(
- ({ variant = 'default', children, ...props }, ref) => {
- // Get theme context for component-level variant overrides (optional)
- const themeContext = useContext(ThemeContext);
- const themeVariantOverride = themeContext?.theme.components?.{componentName}?.variants?.[variant];
-
- return (
- <div
- ref={ref}
- {...stylex.props(
- styles.base,
- variants[variant],
- themeVariantOverride
- )}
- {...props}
- >
- {children}
- </div>
- );
- }
-);
-
-{ComponentName}.displayName = '{ComponentName}';
-```
-
-### 2. index.ts (Exports)
-
-```tsx
-export { {ComponentName} } from './{ComponentName}';
-export type { {ComponentName}Props, {ComponentName}Variant } from './{ComponentName}';
-```
-
-### 3. {ComponentName}.doc.mjs
-
-```js
-/** @type {import('../docs-types').ComponentDoc} */
-
-export const docs = {
- name: '{ComponentName}',
- description: 'Brief description of the component.',
- features: ['Variants: list available variants'],
- props: [
- {
- name: 'variant',
- type: "'{variant1}' | '{variant2}'",
- description: 'Visual style variant',
- default: "'default'",
- },
- {
- name: 'children',
- type: 'ReactNode',
- description: 'Component content',
- required: true,
- },
- ],
- examples: [
- {
- label: 'Basic',
- code: `<{ComponentName} variant="default">Content</{ComponentName}>`,
- },
- ],
- theming: {
- componentKey: '{componentName}',
- surfaces: [{name: 'root', description: 'Outer wrapper element'}],
- },
-};
-```
-
-### 4. Update /packages/core/src/index.ts
-
-Add export for the new component:
-
-```tsx
-export * from './{ComponentName}';
-```
-
-## Key Patterns to Follow
-
-1. **Derive types from StyleX objects**: Use `keyof typeof variants` for variant types
-2. **Use tokens**: Import from `../theme/tokens.stylex` - never use hardcoded values
-3. **SYNC comments**: List all files that need updating when the component changes
-4. **Theme variant ingestion**: Use `ThemeContext` to apply theme-level variant overrides on top of defaults
-5. **Module augmentation**: Use `declare module` to register the component's variant type with `ComponentStyles` - this keeps theme types decoupled from component imports
-
-## Token Reference
-
-Available tokens from `tokens.stylex`:
-
-- `colorTokens`: accent, surface, textPrimary, hoverOverlay, pressedOverlay, focusOutline, negative, etc.
-- `spacingTokens`: space0, space0_5, space1, space2, space3, space4, space5, space6, space7
-- `radiusTokens`: rounded, container, element, content
-- `transitionTokens`: fast, normal
-- `typographyTokens`: fontFamilyBody, fontFamilyCode, fontFamilyHeading
-
-## Reference
-
-See the [Component Authoring Guide](https://github.com/facebookexperimental/xds/wiki/Component-Authoring-Guide) on the wiki for the complete Button implementation with advanced patterns like loading states and hover overlays.
-
-## After Creation
-
-1. Run `yarn workspace @xds/core build` to verify the build
-2. Create stories in `/apps/storybook/stories/{ComponentName}.stories.tsx` (import from `@xds/core/{ComponentName}`)
-3. Add tests in `/packages/core/src/{ComponentName}/{ComponentName}.test.tsx`
+Follow the two-phase protocol documented on the XDS wiki:
+
+1. **Specification Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Specification-Protocol
+2. **Build Protocol**: https://github.com/facebookexperimental/xds/wiki/Component-Build-Protocol
+
+### Quick reference
+
+- Read the spec thoroughly — it's the contract
+- Study sibling components in the same family for patterns
+- Create files in `packages/core/src/{ComponentName}/`:
+ - `XDS{ComponentName}.tsx` — main component
+ - `XDS{ComponentName}.test.tsx` — unit tests
+ - `{ComponentName}.doc.mjs` — typed docs (ComponentDoc)
+ - `index.ts` — public exports
+ - `README.md` — directory README (see Tokenizer/README.md for the format)
+- Create `apps/storybook/stories/{ComponentName}.stories.tsx`
+- Wire up: add to `packages/core/src/index.ts`
+- Run `node scripts/sync-exports.js` to update package.json exports
+- Run `yarn build && yarn test && yarn lint`
+
+### Key conventions
+
+- **API Conventions**: https://github.com/facebookexperimental/xds/wiki/API-Conventions
+- **Theming**: Use `xdsClassName()` for theme targets — see https://github.com/facebookexperimental/xds/wiki/Theming-Infrastructure
+- **Compose, don't rebuild** — use existing XDS components (XDSField, XDSIcon, etc.)
+- **displayName** — always set it
+- **:hover guards** — all `:hover` in `@media (hover: hover)`
+- **Spacing/elevation tokens** — never raw px or boxShadow strings
diff --git a/apps/storybook/stories/MultiSelector.stories.tsx b/apps/storybook/stories/MultiSelector.stories.tsx
new file mode 100644
index 0000000000..ca7fe4f410
--- /dev/null
+++ b/apps/storybook/stories/MultiSelector.stories.tsx
@@ -0,0 +1,357 @@
+import type {Meta, StoryObj} from '@storybook/react';
+import {useState} from 'react';
+import {XDSMultiSelector} from '@xds/core/MultiSelector';
+
+const meta: Meta<typeof XDSMultiSelector> = {
+ title: 'Form/XDSMultiSelector',
+ component: XDSMultiSelector,
+ tags: ['autodocs'],
+ parameters: {
+ layout: 'centered',
+ },
+ decorators: [
+ Story => (
+ <div style={{width: 300}}>
+ <Story />
+ </div>
+ ),
+ ],
+ argTypes: {
+ label: {control: 'text'},
+ isLabelHidden: {control: 'boolean'},
+ description: {control: 'text'},
+ placeholder: {control: 'text'},
+ size: {control: 'radio', options: ['sm', 'md', 'lg']},
+ triggerDisplay: {
+ control: 'radio',
+ options: ['count', 'labels', 'badges'],
+ },
+ isDisabled: {control: 'boolean'},
+ isOptional: {control: 'boolean'},
+ isRequired: {control: 'boolean'},
+ hasSelectAll: {control: 'boolean'},
+ hasSearch: {control: 'boolean'},
+ },
+};
+
+export default meta;
+type Story = StoryObj<typeof XDSMultiSelector>;
+
+// Basic with strings
+export const Default: Story = {
+ render: args => {
+ const [value, setValue] = useState<string[]>(['Role', 'Created']);
+ return (
+ <XDSMultiSelector
+ {...args}
+ label={args.label ?? 'Columns'}
+ options={args.options ?? ['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={value}
+ onChange={setValue}
+ />
+ );
+ },
+ args: {
+ placeholder: 'Select columns...',
+ },
+};
+
+// With sections
+export const Sections: Story = {
+ render: () => {
+ const [value, setValue] = useState<string[]>([]);
+ return (
+ <XDSMultiSelector
+ label="Permissions"
+ options={[
+ {
+ type: 'section',
+ title: 'Read',
+ options: [
+ {value: 'read_posts', label: 'Read posts'},
+ {value: 'read_comments', label: 'Read comments'},
+ {value: 'read_users', label: 'Read users'},
+ ],
+ },
+ {
+ type: 'section',
+ title: 'Write',
+ options: [
+ {value: 'write_posts', label: 'Write posts'},
+ {value: 'write_comments', label: 'Write comments'},
+ ],
+ },
+ ]}
+ value={value}
+ onChange={setValue}
+ placeholder="Select permissions..."
+ />
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// With Select All
+export const SelectAll: Story = {
+ render: () => {
+ const [value, setValue] = useState<string[]>([]);
+ return (
+ <XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role', 'Status', 'Created', 'Updated']}
+ value={value}
+ onChange={setValue}
+ hasSelectAll
+ placeholder="Select columns..."
+ />
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Searchable
+export const Searchable: Story = {
+ render: () => {
+ const [value, setValue] = useState<string[]>([]);
+ return (
+ <XDSMultiSelector
+ label="Countries"
+ options={[
+ 'United States',
+ 'United Kingdom',
+ 'Canada',
+ 'Australia',
+ 'Germany',
+ 'France',
+ 'Japan',
+ 'Brazil',
+ 'India',
+ 'Mexico',
+ ]}
+ value={value}
+ onChange={setValue}
+ hasSearch
+ hasSelectAll
+ placeholder="Select countries..."
+ />
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Trigger display modes
+export const TriggerModes: Story = {
+ render: () => {
+ const [value1, setValue1] = useState<string[]>(['Name', 'Email']);
+ const [value2, setValue2] = useState<string[]>(['Name', 'Email', 'Role']);
+ const [value3, setValue3] = useState<string[]>([
+ 'Name',
+ 'Email',
+ 'Role',
+ 'Status',
+ 'Created',
+ ]);
+ return (
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
+ <XDSMultiSelector
+ label="Count (default)"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={value1}
+ onChange={setValue1}
+ triggerDisplay="count"
+ />
+ <XDSMultiSelector
+ label="Labels"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={value2}
+ onChange={setValue2}
+ triggerDisplay="labels"
+ />
+ <XDSMultiSelector
+ label="Badges"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={value3}
+ onChange={setValue3}
+ triggerDisplay="badges"
+ maxBadges={3}
+ />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Disabled items
+export const DisabledItems: Story = {
+ render: () => {
+ const [value, setValue] = useState<string[]>(['admin']);
+ return (
+ <XDSMultiSelector
+ label="Roles"
+ options={[
+ {value: 'admin', label: 'Admin', disabled: true},
+ {value: 'editor', label: 'Editor'},
+ {value: 'viewer', label: 'Viewer'},
+ {value: 'guest', label: 'Guest'},
+ ]}
+ value={value}
+ onChange={setValue}
+ hasSelectAll
+ placeholder="Select roles..."
+ />
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Status variants
+export const Status: Story = {
+ render: () => {
+ const [value1, setValue1] = useState<string[]>([]);
+ const [value2, setValue2] = useState<string[]>(['Email']);
+ const [value3, setValue3] = useState<string[]>(['Name', 'Email']);
+ return (
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
+ <XDSMultiSelector
+ label="Error"
+ options={['Name', 'Email', 'Role']}
+ value={value1}
+ onChange={setValue1}
+ status={{type: 'error', message: 'Please select at least one column'}}
+ placeholder="Select..."
+ />
+ <XDSMultiSelector
+ label="Warning"
+ options={['Name', 'Email', 'Role']}
+ value={value2}
+ onChange={setValue2}
+ status={{type: 'warning', message: 'Email column has issues'}}
+ />
+ <XDSMultiSelector
+ label="Success"
+ options={['Name', 'Email', 'Role']}
+ value={value3}
+ onChange={setValue3}
+ status={{type: 'success'}}
+ />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Size variants
+export const Sizes: Story = {
+ render: () => {
+ const [value1, setValue1] = useState<string[]>([]);
+ const [value2, setValue2] = useState<string[]>([]);
+ const [value3, setValue3] = useState<string[]>([]);
+ return (
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
+ <XDSMultiSelector
+ label="Small"
+ size="sm"
+ options={['Name', 'Email', 'Role']}
+ value={value1}
+ onChange={setValue1}
+ placeholder="Small (28px)"
+ />
+ <XDSMultiSelector
+ label="Medium"
+ size="md"
+ options={['Name', 'Email', 'Role']}
+ value={value2}
+ onChange={setValue2}
+ placeholder="Medium (32px)"
+ />
+ <XDSMultiSelector
+ label="Large"
+ size="lg"
+ options={['Name', 'Email', 'Role']}
+ value={value3}
+ onChange={setValue3}
+ placeholder="Large (36px)"
+ />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Form composition
+export const FormComposition: Story = {
+ render: () => {
+ const [columns, setColumns] = useState<string[]>(['name', 'email']);
+ const [filters, setFilters] = useState<string[]>([]);
+ return (
+ <div
+ style={{display: 'flex', flexDirection: 'column', gap: 16, width: 300}}>
+ <XDSMultiSelector
+ label="Visible columns"
+ description="Choose which columns to display in the table"
+ options={[
+ {value: 'name', label: 'Name'},
+ {value: 'email', label: 'Email'},
+ {value: 'role', label: 'Role'},
+ {value: 'status', label: 'Status'},
+ {value: 'created', label: 'Created at'},
+ ]}
+ value={columns}
+ onChange={setColumns}
+ hasSelectAll
+ isRequired
+ triggerDisplay="labels"
+ />
+ <XDSMultiSelector
+ label="Status filter"
+ description="Filter by status"
+ options={['Active', 'Inactive', 'Pending', 'Archived']}
+ value={filters}
+ onChange={setFilters}
+ isOptional
+ triggerDisplay="badges"
+ placeholder="All statuses"
+ />
+ </div>
+ );
+ },
+ decorators: [Story => <Story />],
+};
+
+// Column visibility
+export const ColumnVisibility: Story = {
+ render: () => {
+ const allColumns = [
+ {value: 'name', label: 'Name'},
+ {value: 'email', label: 'Email'},
+ {value: 'role', label: 'Role'},
+ {value: 'status', label: 'Status'},
+ {value: 'created', label: 'Created'},
+ {value: 'updated', label: 'Updated'},
+ {value: 'actions', label: 'Actions'},
+ ];
+ const [visible, setVisible] = useState<string[]>([
+ 'name',
+ 'email',
+ 'role',
+ 'status',
+ ]);
+ return (
+ <XDSMultiSelector
+ label="Columns"
+ isLabelHidden
+ options={allColumns}
+ value={visible}
+ onChange={setVisible}
+ hasSelectAll
+ hasSearch
+ triggerDisplay="count"
+ placeholder="Columns"
+ />
+ );
+ },
+ decorators: [Story => <Story />],
+};
diff --git a/packages/core/package.json b/packages/core/package.json
index f1732472c7..6f7a1e5227 100644
--- a/packages/core/package.json
+++ b/packages/core/package.json
@@ -208,6 +208,12 @@
"import": "./dist/MoreMenu/index.mjs",
"require": "./dist/MoreMenu/index.js"
},
+ "./MultiSelector": {
+ "source": "./src/MultiSelector/index.ts",
+ "types": "./dist/MultiSelector/index.d.ts",
+ "import": "./dist/MultiSelector/index.mjs",
+ "require": "./dist/MultiSelector/index.js"
+ },
"./NavIcon": {
"source": "./src/NavIcon/index.ts",
"types": "./dist/NavIcon/index.d.ts",
diff --git a/packages/core/src/MultiSelector/MultiSelector.doc.mjs b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
new file mode 100644
index 0000000000..3e66a29717
--- /dev/null
+++ b/packages/core/src/MultiSelector/MultiSelector.doc.mjs
@@ -0,0 +1,237 @@
+/** @type {import('../docs-types').ComponentDoc} */
+
+export const docs = {
+ name: 'MultiSelector',
+ description:
+ 'Multi-select dropdown with checkboxes for choosing multiple items from a list. For small, finite sets like column toggles or filter facets — not a replacement for XDSTokenizer.',
+ features: [
+ 'Checkbox-based multi-select — dropdown stays open on toggle',
+ 'Supports string items, object items with optional icon and disabled state, dividers, and labeled sections',
+ 'Optional select-all with indeterminate state',
+ 'Optional search filtering',
+ 'Three trigger display modes: count, labels, badges',
+ 'Integrates with XDS field conventions: label, description, isRequired, isOptional, isLabelHidden, status',
+ 'Size variants: sm, md, lg',
+ 'Full keyboard navigation with typeahead support',
+ 'Accessible — role="combobox" trigger, role="listbox" with aria-multiselectable, real checkbox inputs',
+ ],
+ keyboard:
+ '↑↓ navigate, Enter/Space toggle, Escape close, Home/End jump, A-Z typeahead (when search not shown).',
+ accessibility: [
+ 'Uses role="combobox" on the trigger button.',
+ 'Dropdown listbox uses aria-multiselectable="true".',
+ 'Each option uses role="option" with aria-selected.',
+ 'Real XDSCheckboxInput for each item — no fake checkboxes.',
+ 'Select-all checkbox rendered outside role="listbox".',
+ 'Search input uses role="searchbox" with aria-controls.',
+ ],
+ theming: {
+ targets: [
+ {className: 'xds-multi-selector', visualProps: ['size', 'status']},
+ ],
+ },
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role', 'Status']}
+ value={selected}
+ onChange={setSelected}
+/>`,
+ },
+ {
+ label: 'With select all and search',
+ code: `<XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role', 'Status', 'Created']}
+ value={selected}
+ onChange={setSelected}
+ hasSelectAll
+ hasSearch
+/>`,
+ },
+ {
+ label: 'Badges trigger display',
+ code: `<XDSMultiSelector
+ label="Filters"
+ options={['Active', 'Inactive', 'Pending', 'Archived']}
+ value={selected}
+ onChange={setSelected}
+ triggerDisplay="badges"
+ maxBadges={2}
+/>`,
+ },
+ {
+ label: 'Sections',
+ code: `<XDSMultiSelector
+ label="Permissions"
+ options={[
+ {type: 'section', title: 'Read', options: [
+ {value: 'read_posts', label: 'Read posts'},
+ {value: 'read_comments', label: 'Read comments'},
+ ]},
+ {type: 'section', title: 'Write', options: [
+ {value: 'write_posts', label: 'Write posts'},
+ {value: 'write_comments', label: 'Write comments'},
+ ]},
+ ]}
+ value={selected}
+ onChange={setSelected}
+/>`,
+ },
+ ],
+ components: [
+ {
+ name: 'XDSMultiSelector',
+ description:
+ 'Multi-select dropdown with checkboxes for choosing multiple items.',
+ props: [
+ {
+ name: 'label',
+ type: 'string',
+ description: 'Label text for accessibility.',
+ required: true,
+ },
+ {
+ name: 'options',
+ type: 'XDSMultiSelectorOptionType[]',
+ description:
+ 'Array of items — strings, objects with value/label/icon/disabled, dividers, or sections.',
+ required: true,
+ },
+ {
+ name: 'value',
+ type: 'string[]',
+ description: 'Currently selected values.',
+ required: true,
+ },
+ {
+ name: 'onChange',
+ type: '(value: string[]) => void',
+ description: 'Callback fired when the selection changes.',
+ required: true,
+ },
+ {
+ name: 'onChangeAction',
+ type: '(value: string[]) => void | Promise<void>',
+ description: 'Async action on change. Fires after onChange.',
+ },
+ {
+ name: 'placeholder',
+ type: 'string',
+ description: 'Placeholder text shown when no value is selected.',
+ default: "'Select...'",
+ },
+ {
+ name: 'size',
+ type: "'sm' | 'md' | 'lg'",
+ description: 'Size variant for the selector.',
+ default: "'md'",
+ },
+ {
+ name: 'triggerDisplay',
+ type: "'count' | 'labels' | 'badges'",
+ description: 'How to display selected items in the trigger.',
+ default: "'count'",
+ },
+ {
+ name: 'maxBadges',
+ type: 'number',
+ description:
+ 'Maximum badges to show before "+N". Only for triggerDisplay="badges".',
+ default: '3',
+ },
+ {
+ name: 'hasSelectAll',
+ type: 'boolean',
+ description: 'Whether to show a select-all checkbox.',
+ },
+ {
+ name: 'selectAllLabel',
+ type: 'string',
+ description: 'Label for the select-all checkbox.',
+ default: "'Select all'",
+ },
+ {
+ name: 'hasSearch',
+ type: 'boolean',
+ description: 'Whether to show a search input for filtering options.',
+ },
+ {
+ name: 'searchPlaceholder',
+ type: 'string',
+ description: 'Placeholder text for the search input.',
+ default: "'Search...'",
+ },
+ {
+ name: 'isDisabled',
+ type: 'boolean',
+ description: 'Disables the selector.',
+ },
+ {
+ name: 'isLabelHidden',
+ type: 'boolean',
+ description: 'Visually hides the label while keeping it accessible.',
+ },
+ {
+ name: 'description',
+ type: 'string',
+ description: 'Helper text displayed below the label.',
+ },
+ {
+ name: 'isOptional',
+ type: 'boolean',
+ description: 'Marks the field as optional.',
+ },
+ {
+ name: 'isRequired',
+ type: 'boolean',
+ description: 'Marks the field as required.',
+ },
+ {
+ name: 'isLoading',
+ type: 'boolean',
+ description: 'Shows a loading spinner in the trigger.',
+ },
+ {
+ name: 'status',
+ type: "{type: 'error' | 'warning' | 'success', message?: string}",
+ description: 'Validation status with an optional message.',
+ },
+ {
+ name: 'children',
+ type: '(option: XDSMultiSelectorOptionData) => ReactNode',
+ description: 'Custom render function for each option in the dropdown.',
+ },
+ {
+ name: 'xstyle',
+ type: 'StyleXStyles',
+ description:
+ 'StyleX styles for layout customization. Must be a stylex.create() value.',
+ },
+ ],
+ examples: [
+ {
+ label: 'Basic',
+ code: `<XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role']}
+ value={selected}
+ onChange={setSelected}
+/>`,
+ },
+ {
+ label: 'With select all',
+ code: `<XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role']}
+ value={selected}
+ onChange={setSelected}
+ hasSelectAll
+/>`,
+ },
+ ],
+ },
+ ],
+};
diff --git a/packages/core/src/MultiSelector/README.md b/packages/core/src/MultiSelector/README.md
new file mode 100644
index 0000000000..a1c99ba729
--- /dev/null
+++ b/packages/core/src/MultiSelector/README.md
@@ -0,0 +1,70 @@
+# MultiSelector
+
+Multi-select dropdown with checkboxes for choosing multiple items from a list.
+
+<!-- SYNC: When files in this directory change, update this document. -->
+
+## Overview
+
+XDSMultiSelector is a checkbox dropdown for small, finite lists — column toggles, filter facets, permissions. For large/open sets with typeahead search, use XDSTokenizer instead.
+
+- **Checkbox items** — real `XDSCheckboxInput` for each option
+- **Select all** — optional toggle with indeterminate state
+- **Search** — optional filter-in-place
+- **Trigger display** — count, labels, or badge chips
+- **Sections** — reuses `XDSSelector` option type model
+- **Selected-first sort** — selected items sort to top on open (stable during interaction)
+
+## Import
+
+```tsx
+import {XDSMultiSelector} from '@xds/core/MultiSelector';
+```
+
+## Usage
+
+```tsx
+<XDSMultiSelector
+ label="Columns"
+ options={['Name', 'Email', 'Role', 'Status']}
+ value={selected}
+ onChange={setSelected}
+ hasSelectAll
+/>
+```
+
+## Key Props
+
+| Prop | Type | Default | Description |
+| ---------------- | --------------------------------- | --------- | ----------------------------------------------- |
+| `label` | `string` | required | Accessible label |
+| `options` | `XDSMultiSelectorOptionType[]` | required | Items — strings, objects, dividers, or sections |
+| `value` | `string[]` | required | Currently selected values |
+| `onChange` | `(value: string[]) => void` | required | Selection change callback |
+| `hasSelectAll` | `boolean` | `false` | Show select-all toggle |
+| `hasSearch` | `boolean` | `false` | Show search/filter input |
+| `triggerDisplay` | `'count' \| 'labels' \| 'badges'` | `'count'` | How trigger shows selections |
+| `maxBadges` | `number` | `3` | Max badges before "+N" |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size variant |
+| `status` | `{type, message?}` | — | Validation state |
+| `isDisabled` | `boolean` | `false` | Disable the selector |
+| `onChangeAction` | `(value) => Promise` | — | Async action with optimistic UI |
+
+## Theming
+
+The trigger renders `xdsClassName('multi-selector', {size, status})`. Theme authors
+target these classes via `defineTheme({ components })`:
+
+```ts
+defineTheme({
+ name: 'custom',
+ components: {
+ 'multi-selector': {
+ base: {borderRadius: 'var(--radius-3)'},
+ 'size:sm': {fontSize: '12px'},
+ },
+ },
+});
+```
+
+See the [Theming Infrastructure wiki](https://github.com/facebookexperimental/xds/wiki/Theming-Infrastructure).
diff --git a/packages/core/src/MultiSelector/XDSMultiSelector.test.tsx b/packages/core/src/MultiSelector/XDSMultiSelector.test.tsx
new file mode 100644
index 0000000000..211918ffd2
--- /dev/null
+++ b/packages/core/src/MultiSelector/XDSMultiSelector.test.tsx
@@ -0,0 +1,575 @@
+/**
+ * @file XDSMultiSelector.test.tsx
+ * @input Uses vitest, @testing-library/react, @testing-library/user-event
+ * @output Unit tests for XDSMultiSelector
+ * @position Tests; validates XDSMultiSelector behavior
+ *
+ * SYNC: When XDSMultiSelector.tsx API changes, update these tests.
+ */
+
+import {describe, it, expect, vi, beforeEach} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import {XDSMultiSelector} from './XDSMultiSelector';
+
+// Mock showPopover and hidePopover methods since they're not implemented in jsdom
+beforeEach(() => {
+ HTMLElement.prototype.showPopover = vi.fn(function (this: HTMLElement) {
+ this.setAttribute('popover-open', '');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'open'});
+ this.dispatchEvent(event);
+ });
+ HTMLElement.prototype.hidePopover = vi.fn(function (this: HTMLElement) {
+ this.removeAttribute('popover-open');
+ const event = new Event('toggle', {bubbles: false});
+ Object.defineProperty(event, 'newState', {value: 'closed'});
+ this.dispatchEvent(event);
+ });
+ const originalMatches = HTMLElement.prototype.matches;
+ HTMLElement.prototype.matches = function (selector: string) {
+ if (selector === ':popover-open') {
+ return this.hasAttribute('popover-open');
+ }
+ return originalMatches.call(this, selector);
+ };
+});
+
+// Helper: jsdom popover content is in the DOM but may not be
+// "visible" in the accessibility tree. Use hidden: true to find it.
+const h = {hidden: true} as const;
+
+describe('XDSMultiSelector', () => {
+ const defaultOptions = ['Apple', 'Banana', 'Orange'];
+
+ it('renders with label', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByLabelText('Fruit')).toBeInTheDocument();
+ });
+
+ it('renders placeholder when no value selected', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ placeholder="Pick fruits..."
+ />,
+ );
+ expect(screen.getByText('Pick fruits...')).toBeInTheDocument();
+ });
+
+ it('shows count display by default', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={['Apple', 'Banana']}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByText('2 selected')).toBeInTheDocument();
+ });
+
+ it('shows labels display', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={['Apple', 'Banana']}
+ onChange={() => {}}
+ triggerDisplay="labels"
+ />,
+ );
+ expect(screen.getByText('Apple, Banana')).toBeInTheDocument();
+ });
+
+ it('shows labels display with overflow', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}
+ value={['Apple', 'Banana', 'Orange', 'Mango', 'Pineapple']}
+ onChange={() => {}}
+ triggerDisplay="labels"
+ />,
+ );
+ expect(screen.getByText('Apple, Banana, Orange, +2')).toBeInTheDocument();
+ });
+
+ it('opens dropdown on click', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+ await user.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+ });
+
+ it('toggles item on click without closing dropdown', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={onChange}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+
+ const options = screen.getAllByRole('option', h);
+ await user.click(options[0]);
+
+ expect(onChange).toHaveBeenCalledWith(['Apple']);
+ // Dropdown should still be open
+ expect(screen.getByRole('combobox')).toHaveAttribute(
+ 'aria-expanded',
+ 'true',
+ );
+ });
+
+ it('deselects item when clicking selected item', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={['Apple', 'Banana']}
+ onChange={onChange}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ await user.click(options[0]); // Click Apple to deselect
+
+ expect(onChange).toHaveBeenCalledWith(['Banana']);
+ });
+
+ it('does not toggle disabled items', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={[
+ {value: 'apple', label: 'Apple', disabled: true},
+ {value: 'banana', label: 'Banana'},
+ ]}
+ value={[]}
+ onChange={onChange}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ await user.click(options[0]); // Click disabled Apple
+
+ expect(onChange).not.toHaveBeenCalled();
+ });
+
+ it('renders disabled state', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ isDisabled
+ />,
+ );
+ expect(screen.getByRole('combobox')).toBeDisabled();
+ });
+
+ it('has correct ARIA attributes', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ isRequired
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ expect(trigger).toHaveAttribute('aria-haspopup', 'listbox');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ expect(trigger).toHaveAttribute('aria-required', 'true');
+ });
+
+ it('renders listbox with aria-multiselectable', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const listbox = screen.getByRole('listbox', h);
+ expect(listbox).toHaveAttribute('aria-multiselectable', 'true');
+ });
+
+ it('marks selected options with aria-selected', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={['Apple']}
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ expect(options[0]).toHaveAttribute('aria-selected', 'true');
+ expect(options[1]).toHaveAttribute('aria-selected', 'false');
+ });
+
+ it('shows error status with aria-invalid', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ status={{type: 'error', message: 'Required'}}
+ />,
+ );
+ const trigger = screen.getByRole('combobox');
+ expect(trigger).toHaveAttribute('aria-invalid', 'true');
+ expect(screen.getByText('Required')).toBeInTheDocument();
+ });
+
+ it('closes on Escape', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+
+ const trigger = screen.getByRole('combobox');
+ await user.click(trigger);
+ expect(trigger).toHaveAttribute('aria-expanded', 'true');
+
+ await user.keyboard('{Escape}');
+ expect(trigger).toHaveAttribute('aria-expanded', 'false');
+ });
+
+ it('supports keyboard navigation with ArrowDown/ArrowUp', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+
+ const trigger = screen.getByRole('combobox');
+ await user.click(trigger);
+
+ await user.keyboard('{ArrowDown}');
+ const activeId = trigger.getAttribute('aria-activedescendant');
+ expect(activeId).toBeTruthy();
+ });
+
+ it('toggles item with Enter key', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={onChange}
+ />,
+ );
+
+ const trigger = screen.getByRole('combobox');
+ await user.click(trigger);
+ await user.keyboard('{Enter}');
+ expect(onChange).toHaveBeenCalledWith(['Apple']);
+ });
+
+ it('renders select-all checkbox when hasSelectAll', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSelectAll
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ expect(screen.getByLabelText('Select all', h)).toBeInTheDocument();
+ });
+
+ it('select-all selects all enabled items', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={[
+ {value: 'apple', label: 'Apple'},
+ {value: 'banana', label: 'Banana', disabled: true},
+ {value: 'orange', label: 'Orange'},
+ ]}
+ value={[]}
+ onChange={onChange}
+ hasSelectAll
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const selectAll = screen.getByLabelText('Select all', h);
+ await user.click(selectAll);
+
+ expect(onChange).toHaveBeenCalledWith(['apple', 'orange']);
+ });
+
+ it('select-all deselects all when all are selected', async () => {
+ const user = userEvent.setup();
+ const onChange = vi.fn();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={['Apple', 'Banana', 'Orange']}
+ onChange={onChange}
+ hasSelectAll
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const selectAll = screen.getByLabelText('Select all', h);
+ await user.click(selectAll);
+
+ expect(onChange).toHaveBeenCalledWith([]);
+ });
+
+ it('renders search input when hasSearch', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSearch
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ expect(screen.getByRole('searchbox', h)).toBeInTheDocument();
+ });
+
+ it('filters options when searching', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSearch
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const searchInput = screen.getByRole('searchbox', h);
+ await user.type(searchInput, 'app');
+
+ const options = screen.getAllByRole('option', h);
+ expect(options).toHaveLength(1);
+ });
+
+ it('shows empty state when search has no results', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSearch
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const searchInput = screen.getByRole('searchbox', h);
+ await user.type(searchInput, 'xyz');
+
+ expect(screen.getByText('No results found')).toBeInTheDocument();
+ });
+
+ it('renders with description', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ description="Choose your fruits"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+ expect(screen.getByText('Choose your fruits')).toBeInTheDocument();
+ });
+
+ it('supports data-testid', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ data-testid="fruit-selector"
+ />,
+ );
+ expect(screen.getByTestId('fruit-selector')).toBeInTheDocument();
+ });
+
+ it('renders sections with dividers', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={[
+ {value: 'apple', label: 'Apple'},
+ {
+ type: 'section',
+ title: 'Citrus',
+ options: [
+ {value: 'orange', label: 'Orange'},
+ {value: 'lemon', label: 'Lemon'},
+ ],
+ },
+ ]}
+ value={[]}
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ expect(options).toHaveLength(3);
+ const group = screen.getByRole('group', h);
+ expect(group).toHaveAttribute('aria-label', 'Citrus');
+ });
+
+ it('shows loading state with aria-busy', () => {
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ isLoading
+ />,
+ );
+ expect(screen.getByRole('combobox')).toHaveAttribute('aria-busy', 'true');
+ });
+
+ it('renders with custom selectAllLabel', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={defaultOptions}
+ value={[]}
+ onChange={() => {}}
+ hasSelectAll
+ selectAllLabel="Check all"
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ expect(screen.getByLabelText('Check all', h)).toBeInTheDocument();
+ });
+
+ it('sorts selected items to top', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={['Apple', 'Banana', 'Orange']}
+ value={['Orange']}
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ // Orange is selected so it should appear first
+ expect(options[0]).toHaveAttribute('aria-selected', 'true');
+ expect(options[0]).toHaveTextContent('Orange');
+ expect(options[1]).toHaveTextContent('Apple');
+ expect(options[2]).toHaveTextContent('Banana');
+ });
+
+ it('sorts selected items to top within sections', async () => {
+ const user = userEvent.setup();
+ render(
+ <XDSMultiSelector
+ label="Fruit"
+ options={[
+ {
+ type: 'section',
+ title: 'Citrus',
+ options: [
+ {value: 'orange', label: 'Orange'},
+ {value: 'lemon', label: 'Lemon'},
+ {value: 'lime', label: 'Lime'},
+ ],
+ },
+ ]}
+ value={['lime']}
+ onChange={() => {}}
+ />,
+ );
+
+ await user.click(screen.getByRole('combobox'));
+ const options = screen.getAllByRole('option', h);
+ // Lime is selected so it should appear first within the section
+ expect(options[0]).toHaveTextContent('Lime');
+ expect(options[1]).toHaveTextContent('Orange');
+ expect(options[2]).toHaveTextContent('Lemon');
+ });
+
+ it('has displayName', () => {
+ expect(XDSMultiSelector.displayName).toBe('XDSMultiSelector');
+ });
+});
diff --git a/packages/core/src/MultiSelector/XDSMultiSelector.tsx b/packages/core/src/MultiSelector/XDSMultiSelector.tsx
new file mode 100644
index 0000000000..60ccf2e4af
--- /dev/null
+++ b/packages/core/src/MultiSelector/XDSMultiSelector.tsx
@@ -0,0 +1,1006 @@
+'use client';
+
+/**
+ * @file XDSMultiSelector.tsx
+ * @input Uses React, StyleX, useXDSPopover, XDSCheckboxInput, XDSField, XDSBadge, XDSIcon
+ * @output Exports XDSMultiSelector component
+ * @position Core implementation; consumed by index.ts
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/MultiSelector/MultiSelector.doc.mjs
+ * - /packages/core/src/MultiSelector/index.ts
+ */
+
+import React, {
+ useCallback,
+ useId,
+ useMemo,
+ useOptimistic,
+ useRef,
+ useState,
+ useTransition,
+ type ReactNode,
+} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {useXDSPopover} from '../Popover/useXDSPopover';
+import {XDSIcon} from '../Icon';
+import type {XDSIconName} from '../Icon';
+import {
+ XDSField,
+ inputStatusBorderStyles,
+ inputStatusHoverShadowStyles,
+} from '../Field';
+import {XDSDivider} from '../Divider';
+import {XDSSpinner} from '../Spinner';
+import {XDSCheckboxInput} from '../CheckboxInput';
+import {XDSBadge} from '../Badge';
+import {
+ colorVars,
+ sizeVars,
+ spacingVars,
+ radiusVars,
+ shadowVars,
+ durationVars,
+ easeVars,
+ typographyVars,
+ fontWeightVars,
+ typeScaleVars,
+ borderVars,
+} from '../theme/tokens.stylex';
+import type {
+ XDSMultiSelectorOptionType,
+ XDSMultiSelectorOptionData,
+ XDSMultiSelectorStatus,
+} from './types';
+import {
+ isOptionData,
+ isDivider,
+ isSection,
+ normalizeOption,
+ getSelectableOptions,
+} from '../Selector/utils';
+import {useMultiCombobox} from './hooks';
+import {xdsClassName, mergeProps} from '../utils';
+import {XDSBaseProps} from '../XDSBaseProps';
+
+const styles = stylex.create({
+ // Trigger button
+ trigger: {
+ position: 'relative',
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'space-between',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ paddingBlock: spacingVars['--spacing-2'],
+ paddingInline: spacingVars['--spacing-3'],
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: {
+ default: colorVars['--color-border-emphasized'],
+ ':hover': {
+ '@media (hover: hover)': colorVars['--color-border-emphasized'],
+ },
+ },
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-background-surface'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-label-size'],
+ lineHeight: typeScaleVars['--text-label-leading'],
+ color: colorVars['--color-text-primary'],
+ cursor: 'pointer',
+ transitionProperty: 'border-color, outline, box-shadow',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ boxShadow: {
+ default: 'none',
+ ':hover': {
+ '@media (hover: hover)': shadowVars['--shadow-inset-hover'],
+ },
+ },
+ outline: {
+ default: 'none',
+ ':focus': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: '0',
+ },
+ triggerDisabled: {
+ cursor: 'not-allowed',
+ opacity: 0.5,
+ borderColor: colorVars['--color-border-emphasized'],
+ },
+ triggerPlaceholder: {
+ color: colorVars['--color-text-secondary'],
+ },
+ triggerContent: {
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-1'],
+ flexGrow: 1,
+ flexShrink: 1,
+ flexBasis: 0,
+ minWidth: 0,
+ overflow: 'hidden',
+ },
+ triggerText: {
+ overflow: 'hidden',
+ textOverflow: 'ellipsis',
+ whiteSpace: 'nowrap',
+ },
+ triggerBadges: {
+ display: 'flex',
+ flexWrap: 'wrap',
+ gap: spacingVars['--spacing-1'],
+ alignItems: 'center',
+ },
+ triggerOverflow: {
+ flexShrink: 0,
+ fontSize: typeScaleVars['--text-label-size'],
+ color: colorVars['--color-text-secondary'],
+ fontWeight: fontWeightVars['--font-weight-medium'],
+ },
+ triggerIcon: {
+ flexShrink: 0,
+ display: 'flex',
+ alignItems: 'center',
+ justifyContent: 'center',
+ width: 16,
+ height: 16,
+ transitionProperty: 'transform',
+ transitionDuration: durationVars['--duration-fast'],
+ transitionTimingFunction: easeVars['--ease-standard'],
+ transformOrigin: 'center',
+ color: colorVars['--color-icon-secondary'],
+ },
+ triggerIconOpen: {
+ transform: 'rotate(180deg)',
+ },
+ triggerIconStatus: {
+ transition: 'none',
+ },
+
+ // Dropdown container
+ dropdown: {
+ boxSizing: 'border-box',
+ maxHeight: '300px',
+ overflowY: 'auto',
+ padding: spacingVars['--spacing-1'],
+ },
+
+ // Popover container (for anchor positioning)
+ popover: {
+ minWidth: 'anchor-size(width)',
+ marginBlockStart: spacingVars['--spacing-1'],
+ },
+
+ // Search input
+ searchWrapper: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ searchInput: {
+ boxSizing: 'border-box',
+ width: '100%',
+ paddingBlock: spacingVars['--spacing-1'],
+ paddingInline: spacingVars['--spacing-2'],
+ borderWidth: borderVars['--border-width'],
+ borderStyle: 'solid',
+ borderColor: colorVars['--color-border-emphasized'],
+ borderRadius: radiusVars['--radius-element'],
+ backgroundColor: colorVars['--color-background-surface'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-label-size'],
+ color: colorVars['--color-text-primary'],
+ outline: {
+ default: 'none',
+ ':focus': `${borderVars['--border-width']} solid ${colorVars['--color-accent']}`,
+ },
+ outlineOffset: '0',
+ },
+
+ // Select-all wrapper
+ selectAllWrapper: {
+ cursor: 'pointer',
+ },
+
+ // Section divider with label
+ sectionDivider: {
+ marginBlock: spacingVars['--spacing-1'],
+ },
+
+ // Divider
+ divider: {
+ marginBlock: spacingVars['--spacing-1'],
+ },
+
+ // Individual item
+ item: {
+ boxSizing: 'border-box',
+ display: 'flex',
+ alignItems: 'center',
+ gap: spacingVars['--spacing-2'],
+ width: '100%',
+ borderRadius: radiusVars['--radius-element'],
+ cursor: 'pointer',
+ backgroundColor: 'transparent',
+ border: 'none',
+ outline: 'none',
+ },
+ itemHighlighted: {
+ backgroundColor: colorVars['--color-overlay-hover'],
+ },
+ itemDisabled: {
+ opacity: 0.5,
+ cursor: 'not-allowed',
+ },
+
+ // Empty state
+ emptyState: {
+ padding: spacingVars['--spacing-3'],
+ textAlign: 'center',
+ color: colorVars['--color-text-secondary'],
+ fontFamily: typographyVars['--font-family-body'],
+ fontSize: typeScaleVars['--text-label-size'],
+ },
+});
+
+const sizeStyles = stylex.create({
+ sm: {
+ height: sizeVars['--size-element-sm'],
+ },
+ md: {
+ height: sizeVars['--size-element-md'],
+ },
+ lg: {
+ height: sizeVars['--size-element-lg'],
+ },
+});
+
+const itemSizeStyles = stylex.create({
+ sm: {
+ padding: spacingVars['--spacing-1'],
+ },
+ md: {
+ padding: spacingVars['--spacing-2'],
+ },
+ lg: {
+ padding: spacingVars['--spacing-2'],
+ },
+});
+
+const selectAllSizeStyles = stylex.create({
+ sm: {
+ paddingInline: spacingVars['--spacing-1'],
+ paddingBlock: spacingVars['--spacing-0-5'],
+ },
+ md: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+ lg: {
+ paddingInline: spacingVars['--spacing-2'],
+ paddingBlock: spacingVars['--spacing-1'],
+ },
+});
+
+const STATUS_ICON_MAP: Record<XDSMultiSelectorStatusType, XDSIconName> = {
+ warning: 'warning',
+ error: 'xCircle',
+ success: 'checkCircle',
+};
+
+const STATUS_ICON_COLOR_MAP: Record<
+ XDSMultiSelectorStatusType,
+ 'warning' | 'negative' | 'positive'
+> = {
+ warning: 'warning',
+ error: 'negative',
+ success: 'positive',
+};
+
+export type XDSMultiSelectorSize = 'sm' | 'md' | 'lg';
+
+export type XDSMultiSelectorStatusType = 'warning' | 'error' | 'success';
+
+export type {XDSMultiSelectorStatus};
+
+export interface XDSMultiSelectorProps<
+ T extends XDSMultiSelectorOptionType = XDSMultiSelectorOptionType,
+> extends Omit<XDSBaseProps, 'onChange' | 'defaultValue' | 'children'> {
+ /**
+ * Label text for the multi-selector (always rendered for accessibility).
+ */
+ label: string;
+
+ /**
+ * Whether to visually hide the label (still accessible to screen readers).
+ * @default false
+ */
+ isLabelHidden?: boolean;
+
+ /**
+ * Description text displayed between the label and selector.
+ */
+ description?: string;
+
+ /**
+ * Whether the field is optional. Mutually exclusive with isRequired.
+ * @default false
+ */
+ isOptional?: boolean;
+
+ /**
+ * Whether the field is required. Mutually exclusive with isOptional.
+ * @default false
+ */
+ isRequired?: boolean;
+
+ /**
+ * Whether the selector is disabled.
+ * @default false
+ */
+ isDisabled?: boolean;
+
+ /**
+ * The options to display in the selector.
+ * Can be strings, objects, dividers, or sections.
+ */
+ options: T[];
+
+ /**
+ * The currently selected values.
+ */
+ value: string[];
+
+ /**
+ * Callback when selection changes.
+ */
+ onChange: (value: string[]) => void;
+
+ /**
+ * Async action on change. Fires after onChange.
+ */
+ onChangeAction?: (value: string[]) => void | Promise<void>;
+
+ /**
+ * Whether the selector is in a loading state.
+ * @default false
+ */
+ isLoading?: boolean;
+
+ /**
+ * Placeholder text when no value is selected.
+ * @default 'Select...'
+ */
+ placeholder?: string;
+
+ /**
+ * The size of the selector.
+ * @default 'md'
+ */
+ size?: XDSMultiSelectorSize;
+
+ /**
+ * Status indicator for the selector.
+ */
+ status?: XDSMultiSelectorStatus;
+
+ /**
+ * Tooltip text to display in an info icon at the end of the label.
+ */
+ labelTooltip?: string;
+
+ /**
+ * Whether to show a "Select all" checkbox.
+ * @default false
+ */
+ hasSelectAll?: boolean;
+
+ /**
+ * Label for the select-all checkbox.
+ * @default 'Select all'
+ */
+ selectAllLabel?: string;
+
+ /**
+ * Whether to show a search input.
+ * @default false
+ */
+ hasSearch?: boolean;
+
+ /**
+ * Placeholder text for the search input.
+ * @default 'Search...'
+ */
+ searchPlaceholder?: string;
+
+ /**
+ * How to display selected items in the trigger.
+ * - 'count': "3 selected"
+ * - 'labels': "Name, Email, +3"
+ * - 'badges': [Name] [Email] +2
+ * @default 'count'
+ */
+ triggerDisplay?: 'count' | 'labels' | 'badges';
+
+ /**
+ * Maximum number of badges to show before showing "+N".
+ * Only used when triggerDisplay is 'badges'.
+ * @default 3
+ */
+ maxBadges?: number;
+
+ /**
+ * Custom render function for options.
+ * Only called for selectable options (not dividers/sections).
+ */
+ children?: (option: XDSMultiSelectorOptionData) => ReactNode;
+
+ /**
+ * Test ID for testing frameworks.
+ */
+ 'data-testid'?: string;
+}
+
+/**
+ * A multi-select dropdown component with checkboxes for choosing
+ * multiple items from a list of options.
+ *
+ * @example
+ * ```
+ * <XDSMultiSelector
+ * label="Columns"
+ * options={['Name', 'Email', 'Role', 'Status']}
+ * value={selectedColumns}
+ * onChange={setSelectedColumns}
+ * hasSelectAll
+ * />
+ * ```
+ */
+export function XDSMultiSelector<T extends XDSMultiSelectorOptionType>({
+ label,
+ isLabelHidden = false,
+ description,
+ isOptional = false,
+ isRequired = false,
+ isDisabled = false,
+ options,
+ value,
+ onChange,
+ onChangeAction,
+ isLoading = false,
+ placeholder = 'Select...',
+ size = 'md',
+ status,
+ labelTooltip,
+ hasSelectAll = false,
+ selectAllLabel = 'Select all',
+ hasSearch = false,
+ searchPlaceholder = 'Search...',
+ triggerDisplay = 'count',
+ maxBadges = 3,
+ children,
+ 'data-testid': testId,
+ xstyle,
+ className,
+ style,
+}: XDSMultiSelectorProps<T>) {
+ const triggerId = useId();
+ const listboxId = useId();
+ const descriptionId = useId();
+ const statusMessageId = useId();
+ const searchId = useId();
+ const triggerRef = useRef<HTMLButtonElement>(null);
+ const searchRef = useRef<HTMLInputElement>(null);
+
+ const [searchQuery, setSearchQuery] = useState('');
+
+ // Snapshot of which values were selected when the dropdown opened.
+ // Used for sort partitioning so items don't jump during interaction.
+ const selectedAtOpenRef = useRef<Set<string> | null>(null);
+
+ const [, startTransition] = useTransition();
+ const [optimisticValue, setOptimisticValue] = useOptimistic(value);
+ const isBusy = isLoading || optimisticValue !== value;
+
+ // Build aria-describedby
+ const ariaDescribedBy =
+ [
+ description ? descriptionId : null,
+ status?.message ? statusMessageId : null,
+ ]
+ .filter(Boolean)
+ .join(' ') || undefined;
+
+ // Flatten options for keyboard navigation
+ const selectableItems = useMemo(
+ () => getSelectableOptions(options),
+ [options],
+ );
+
+ // Filter items by search query
+ const filteredItems = useMemo(() => {
+ if (!searchQuery) return selectableItems;
+ const query = searchQuery.toLowerCase();
+ return selectableItems.filter(item =>
+ (item.label ?? item.value).toLowerCase().includes(query),
+ );
+ }, [selectableItems, searchQuery]);
+
+ // Layer for dropdown positioning
+ const handleLayerHide = useCallback(() => {
+ setSearchQuery('');
+ selectedAtOpenRef.current = null;
+ triggerRef.current?.focus();
+ }, []);
+
+ const popover = useXDSPopover({
+ hasLightDismiss: true,
+ onHide: handleLayerHide,
+ hasCloseButton: false,
+ hasAutoFocus: false,
+ dialogLabel: `${label} options`,
+ });
+
+ // Handle toggle
+ const handleToggle = useCallback(
+ (itemValue: string) => {
+ const newValue = optimisticValue.includes(itemValue)
+ ? optimisticValue.filter(v => v !== itemValue)
+ : [...optimisticValue, itemValue];
+
+ onChange(newValue);
+ if (onChangeAction) {
+ startTransition(async () => {
+ setOptimisticValue(newValue);
+ await onChangeAction(newValue);
+ });
+ }
+ },
+ [
+ optimisticValue,
+ onChange,
+ onChangeAction,
+ startTransition,
+ setOptimisticValue,
+ ],
+ );
+
+ // Multi-select combobox behavior
+ const {
+ highlightedIndex,
+ getItemId,
+ onTriggerClick,
+ onKeyDown,
+ onItemMouseEnter,
+ } = useMultiCombobox({
+ selectableItems: filteredItems,
+ isDisabled,
+ isOpen: popover.isOpen,
+ hasSearch,
+ onOpen: useCallback(() => {
+ // Snapshot which items are selected at open time — sort is stable during interaction
+ selectedAtOpenRef.current = new Set(optimisticValue);
+
+ popover.show();
+ if (hasSearch) {
+ // Focus search after popover opens
+ requestAnimationFrame(() => {
+ searchRef.current?.focus();
+ });
+ }
+ }, [popover, hasSearch, filteredItems, optimisticValue]),
+ onClose: popover.hide,
+ onToggle: handleToggle,
+ listboxId,
+ });
+
+ // Select-all logic
+ const enabledItems = useMemo(
+ () => filteredItems.filter(item => !item.disabled),
+ [filteredItems],
+ );
+
+ const allEnabledSelected = useMemo(
+ () =>
+ enabledItems.length > 0 &&
+ enabledItems.every(item => optimisticValue.includes(item.value)),
+ [enabledItems, optimisticValue],
+ );
+
+ const someSelected = useMemo(
+ () => enabledItems.some(item => optimisticValue.includes(item.value)),
+ [enabledItems, optimisticValue],
+ );
+
+ const selectAllState: boolean | 'indeterminate' = allEnabledSelected
+ ? true
+ : someSelected
+ ? 'indeterminate'
+ : false;
+
+ const handleSelectAll = useCallback(() => {
+ let newValue: string[];
+ if (allEnabledSelected) {
+ // Deselect all enabled items, keep disabled items that are selected
+ const enabledValues = new Set(enabledItems.map(item => item.value));
+ newValue = optimisticValue.filter(v => !enabledValues.has(v));
+ } else {
+ // Select all enabled items
+ const currentSet = new Set(optimisticValue);
+ newValue = [...optimisticValue];
+ for (const item of enabledItems) {
+ if (!currentSet.has(item.value)) {
+ newValue.push(item.value);
+ }
+ }
+ }
+
+ onChange(newValue);
+ if (onChangeAction) {
+ startTransition(async () => {
+ setOptimisticValue(newValue);
+ await onChangeAction(newValue);
+ });
+ }
+ }, [
+ allEnabledSelected,
+ enabledItems,
+ optimisticValue,
+ onChange,
+ onChangeAction,
+ startTransition,
+ setOptimisticValue,
+ ]);
+
+ // Build trigger display content
+ const selectedLabels = useMemo(() => {
+ return optimisticValue.map(v => {
+ const item = selectableItems.find(i => i.value === v);
+ return item?.label ?? v;
+ });
+ }, [optimisticValue, selectableItems]);
+
+ const renderTriggerContent = useCallback(() => {
+ if (optimisticValue.length === 0) {
+ return <span {...stylex.props(styles.triggerText)}>{placeholder}</span>;
+ }
+
+ switch (triggerDisplay) {
+ case 'count':
+ return (
+ <span {...stylex.props(styles.triggerText)}>
+ {optimisticValue.length} selected
+ </span>
+ );
+
+ case 'labels': {
+ const displayed = selectedLabels.slice(0, 3);
+ const remaining = selectedLabels.length - displayed.length;
+ const text =
+ remaining > 0
+ ? `${displayed.join(', ')}, +${remaining}`
+ : displayed.join(', ');
+ return <span {...stylex.props(styles.triggerText)}>{text}</span>;
+ }
+
+ case 'badges': {
+ const displayed = selectedLabels.slice(0, maxBadges);
+ const remaining = selectedLabels.length - displayed.length;
+ return (
+ <span {...stylex.props(styles.triggerBadges)}>
+ {displayed.map(label => (
+ <XDSBadge key={label} label={label} variant="neutral" />
+ ))}
+ {remaining > 0 && (
+ <span {...stylex.props(styles.triggerOverflow)}>
+ +{remaining}
+ </span>
+ )}
+ </span>
+ );
+ }
+ }
+ }, [optimisticValue, triggerDisplay, selectedLabels, placeholder, maxBadges]);
+
+ // Render search input
+ const renderSearch = useCallback(() => {
+ if (!hasSearch) return null;
+ return (
+ <div {...stylex.props(styles.searchWrapper)}>
+ <input
+ ref={searchRef}
+ id={searchId}
+ role="searchbox"
+ aria-controls={listboxId}
+ aria-label="Search options"
+ type="text"
+ value={searchQuery}
+ onChange={e => setSearchQuery(e.target.value)}
+ onKeyDown={e => {
+ // Let ArrowDown/Up/Escape propagate to parent handler
+ if (
+ e.key === 'ArrowDown' ||
+ e.key === 'ArrowUp' ||
+ e.key === 'Escape'
+ ) {
+ onKeyDown(e);
+ }
+ }}
+ placeholder={searchPlaceholder}
+ {...stylex.props(styles.searchInput)}
+ />
+ </div>
+ );
+ }, [
+ hasSearch,
+ searchId,
+ listboxId,
+ searchQuery,
+ searchPlaceholder,
+ onKeyDown,
+ ]);
+
+ // Render an individual item
+ const renderItem = useCallback(
+ (item: XDSMultiSelectorOptionData, flatIndex: number) => {
+ const isHighlighted = flatIndex === highlightedIndex;
+ const isSelected = optimisticValue.includes(item.value);
+
+ return (
+ <div
+ key={item.value}
+ id={getItemId(flatIndex)}
+ role="option"
+ aria-selected={isSelected}
+ aria-disabled={item.disabled}
+ onClick={() => {
+ if (!item.disabled) {
+ handleToggle(item.value);
+ }
+ }}
+ onMouseEnter={() => onItemMouseEnter(item, flatIndex)}
+ {...stylex.props(
+ styles.item,
+ itemSizeStyles[size],
+ isHighlighted && styles.itemHighlighted,
+ item.disabled && styles.itemDisabled,
+ )}>
+ <XDSCheckboxInput
+ label={children ? '' : (item.label ?? item.value)}
+ isLabelHidden={!!children}
+ value={isSelected}
+ onChange={() => {}}
+ isDisabled={item.disabled}
+ size={size === 'lg' ? 'md' : size}
+ />
+ {children && children(item)}
+ </div>
+ );
+ },
+ [
+ children,
+ highlightedIndex,
+ optimisticValue,
+ getItemId,
+ handleToggle,
+ onItemMouseEnter,
+ size,
+ ],
+ );
+
+ // Render all options (handling sections/dividers and search filtering)
+ const renderOptions = useCallback(() => {
+ // Use the open-time snapshot for sort partitioning (stable during interaction).
+ // Falls back to live value when dropdown isn't open yet.
+ const selectedSet = selectedAtOpenRef.current ?? new Set(optimisticValue);
+
+ if (searchQuery) {
+ // Sort filtered: selected-at-open first, then unselected
+ const selected = filteredItems.filter(item =>
+ selectedSet.has(item.value),
+ );
+ const unselected = filteredItems.filter(
+ item => !selectedSet.has(item.value),
+ );
+ const sorted = [...selected, ...unselected];
+
+ if (sorted.length === 0) {
+ return <div {...stylex.props(styles.emptyState)}>No results found</div>;
+ }
+ return sorted.map((item, index) => renderItem(item, index));
+ }
+
+ // Normal rendering with selected-first sorting (using open-time snapshot)
+ let flatIndex = 0;
+ const elements: ReactNode[] = [];
+ let pendingFlatItems: Array<{
+ item: XDSMultiSelectorOptionData;
+ }> = [];
+
+ const flushFlatItems = () => {
+ if (pendingFlatItems.length === 0) return;
+ const selected = pendingFlatItems.filter(({item}) =>
+ selectedSet.has(item.value),
+ );
+ const unselected = pendingFlatItems.filter(
+ ({item}) => !selectedSet.has(item.value),
+ );
+ const sorted = [...selected, ...unselected];
+ for (const {item} of sorted) {
+ elements.push(renderItem(item, flatIndex));
+ flatIndex++;
+ }
+ pendingFlatItems = [];
+ };
+
+ for (let i = 0; i < options.length; i++) {
+ const option = options[i];
+
+ if (isDivider(option)) {
+ flushFlatItems();
+ elements.push(
+ <XDSDivider key={`divider-${i}`} xstyle={styles.divider} />,
+ );
+ } else if (isSection(option)) {
+ flushFlatItems();
+ // Sort within section: selected-at-open first
+ const sectionOptions = option.options.map(opt => normalizeOption(opt));
+ const selectedInSection = sectionOptions.filter(item =>
+ selectedSet.has(item.value),
+ );
+ const unselectedInSection = sectionOptions.filter(
+ item => !selectedSet.has(item.value),
+ );
+ const sortedSection = [...selectedInSection, ...unselectedInSection];
+
+ const sectionItems: ReactNode[] = [];
+ for (const item of sortedSection) {
+ sectionItems.push(renderItem(item, flatIndex));
+ flatIndex++;
+ }
+ if (option.title) {
+ elements.push(
+ <XDSDivider
+ key={`section-divider-${i}`}
+ label={option.title}
+ xstyle={styles.sectionDivider}
+ />,
+ );
+ }
+ elements.push(
+ <div key={`section-${i}`} role="group" aria-label={option.title}>
+ {sectionItems}
+ </div>,
+ );
+ } else if (isOptionData(option)) {
+ pendingFlatItems.push({item: normalizeOption(option)});
+ }
+ }
+ flushFlatItems();
+
+ return elements;
+ }, [options, renderItem, filteredItems, searchQuery, optimisticValue]);
+
+ return (
+ <XDSField
+ label={label}
+ isLabelHidden={isLabelHidden}
+ description={description}
+ inputID={triggerId}
+ descriptionID={description ? descriptionId : undefined}
+ isOptional={isOptional}
+ isRequired={isRequired}
+ isDisabled={isDisabled}
+ status={
+ status
+ ? {
+ type: status.type,
+ message: status.message,
+ messageID: status.message ? statusMessageId : undefined,
+ }
+ : undefined
+ }
+ labelTooltip={labelTooltip}>
+ <button
+ ref={el => {
+ (
+ triggerRef as React.MutableRefObject<HTMLButtonElement | null>
+ ).current = el;
+ popover.triggerRef(el);
+ }}
+ id={triggerId}
+ type="button"
+ role="combobox"
+ aria-haspopup="listbox"
+ aria-expanded={popover.isOpen}
+ aria-controls={listboxId}
+ aria-activedescendant={
+ popover.isOpen && highlightedIndex >= 0
+ ? getItemId(highlightedIndex)
+ : undefined
+ }
+ aria-describedby={ariaDescribedBy}
+ aria-required={isRequired ? 'true' : undefined}
+ aria-invalid={status?.type === 'error' ? 'true' : undefined}
+ aria-busy={isBusy || undefined}
+ disabled={isDisabled}
+ onClick={onTriggerClick}
+ onKeyDown={onKeyDown}
+ data-testid={testId}
+ {...mergeProps(
+ xdsClassName('multi-selector', {size, status: status?.type ?? null}),
+ stylex.props(
+ styles.trigger,
+ sizeStyles[size],
+ isDisabled && styles.triggerDisabled,
+ optimisticValue.length === 0 && styles.triggerPlaceholder,
+ status && inputStatusBorderStyles[status.type],
+ status && inputStatusHoverShadowStyles[status.type],
+ xstyle,
+ ),
+ className,
+ style,
+ )}>
+ <span {...stylex.props(styles.triggerContent)}>
+ {renderTriggerContent()}
+ </span>
+ {isBusy && <XDSSpinner size="sm" />}
+ <span
+ {...stylex.props(
+ styles.triggerIcon,
+ !status && popover.isOpen && styles.triggerIconOpen,
+ status && styles.triggerIconStatus,
+ )}>
+ {status ? (
+ <XDSIcon
+ icon={STATUS_ICON_MAP[status.type]}
+ size="sm"
+ color={STATUS_ICON_COLOR_MAP[status.type]}
+ />
+ ) : (
+ <XDSIcon icon="chevronDown" size="sm" color="inherit" />
+ )}
+ </span>
+ </button>
+
+ {popover.render(
+ <div {...stylex.props(styles.dropdown)}>
+ {renderSearch()}
+ {hasSelectAll && (
+ <>
+ <div
+ {...stylex.props(
+ styles.selectAllWrapper,
+ selectAllSizeStyles[size],
+ )}
+ onClick={handleSelectAll}>
+ <XDSCheckboxInput
+ label={selectAllLabel}
+ value={selectAllState}
+ onChange={() => {}}
+ size={size === 'lg' ? 'md' : size}
+ />
+ </div>
+ <XDSDivider xstyle={styles.divider} />
+ </>
+ )}
+ <div
+ id={listboxId}
+ role="listbox"
+ aria-multiselectable="true"
+ aria-labelledby={triggerId}>
+ {renderOptions()}
+ </div>
+ </div>,
+ {
+ placement: 'below',
+ alignment: 'start',
+ xstyle: styles.popover,
+ },
+ )}
+ </XDSField>
+ );
+}
+
+XDSMultiSelector.displayName = 'XDSMultiSelector';
diff --git a/packages/core/src/MultiSelector/hooks.ts b/packages/core/src/MultiSelector/hooks.ts
new file mode 100644
index 0000000000..88f49704d2
--- /dev/null
+++ b/packages/core/src/MultiSelector/hooks.ts
@@ -0,0 +1,219 @@
+'use client';
+
+/**
+ * @file hooks.ts
+ * @input Uses React hooks, XDSMultiSelectorOptionData type
+ * @output Exports useMultiCombobox hook
+ * @position Internal hook; used by XDSMultiSelector.tsx
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/MultiSelector/index.ts
+ */
+
+import {useCallback, useRef, useState} from 'react';
+import type {XDSMultiSelectorOptionData} from './types';
+
+interface UseMultiComboboxOptions {
+ selectableItems: XDSMultiSelectorOptionData[];
+ isDisabled?: boolean;
+ isOpen: boolean;
+ hasSearch?: boolean;
+ onOpen: () => void;
+ onClose: () => void;
+ onToggle: (itemValue: string) => void;
+ listboxId: string;
+}
+
+interface UseMultiComboboxResult {
+ highlightedIndex: number;
+ setHighlightedIndex: (index: number) => void;
+ getItemId: (index: number) => string;
+ onTriggerClick: () => void;
+ onKeyDown: (e: React.KeyboardEvent) => void;
+ onItemMouseEnter: (item: XDSMultiSelectorOptionData, index: number) => void;
+}
+
+/**
+ * Handles keyboard navigation and toggle logic for multi-select combobox.
+ * Unlike useCombobox (single-select), toggling an item does NOT close the dropdown.
+ */
+export function useMultiCombobox({
+ selectableItems,
+ isDisabled = false,
+ isOpen,
+ hasSearch = false,
+ onOpen,
+ onClose,
+ onToggle,
+ listboxId,
+}: UseMultiComboboxOptions): UseMultiComboboxResult {
+ const [highlightedIndex, setHighlightedIndex] = useState<number>(-1);
+ const [typeahead, setTypeahead] = useState('');
+ const typeaheadTimeoutRef = useRef<ReturnType<typeof setTimeout> | undefined>(
+ undefined,
+ );
+
+ const getItemId = useCallback(
+ (index: number) => `${listboxId}-item-${index}`,
+ [listboxId],
+ );
+
+ const getEnabledIndices = useCallback(() => {
+ return selectableItems
+ .map((item, i) => (!item.disabled ? i : -1))
+ .filter(i => i >= 0);
+ }, [selectableItems]);
+
+ const closeAndReset = useCallback(() => {
+ setHighlightedIndex(-1);
+ onClose();
+ }, [onClose]);
+
+ const onTriggerClick = useCallback(() => {
+ if (isDisabled) return;
+ if (isOpen) {
+ closeAndReset();
+ } else {
+ onOpen();
+ // If search is present, don't highlight any item (focus goes to search)
+ if (!hasSearch) {
+ setHighlightedIndex(0);
+ }
+ }
+ }, [isDisabled, isOpen, onOpen, closeAndReset, hasSearch]);
+
+ const onItemMouseEnter = useCallback(
+ (item: XDSMultiSelectorOptionData, index: number) => {
+ if (!item.disabled) {
+ setHighlightedIndex(index);
+ }
+ },
+ [],
+ );
+
+ const onKeyDown = useCallback(
+ (e: React.KeyboardEvent) => {
+ if (isDisabled) return;
+
+ const enabledIndices = getEnabledIndices();
+
+ switch (e.key) {
+ case 'ArrowDown':
+ e.preventDefault();
+ if (!isOpen) {
+ onOpen();
+ setHighlightedIndex(0);
+ } else {
+ const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
+ const nextPos = Math.min(
+ currentEnabledPos + 1,
+ enabledIndices.length - 1,
+ );
+ setHighlightedIndex(enabledIndices[nextPos] ?? highlightedIndex);
+ }
+ break;
+
+ case 'ArrowUp':
+ e.preventDefault();
+ if (!isOpen) {
+ onOpen();
+ setHighlightedIndex(selectableItems.length - 1);
+ } else {
+ const currentEnabledPos = enabledIndices.indexOf(highlightedIndex);
+ const prevPos = Math.max(currentEnabledPos - 1, 0);
+ setHighlightedIndex(enabledIndices[prevPos] ?? highlightedIndex);
+ }
+ break;
+
+ case 'Enter':
+ case ' ':
+ // Don't intercept Space when search input is focused
+ if (e.key === ' ' && hasSearch) {
+ break;
+ }
+ e.preventDefault();
+ if (isOpen && highlightedIndex >= 0) {
+ const item = selectableItems[highlightedIndex];
+ if (item && !item.disabled) {
+ onToggle(item.value);
+ }
+ } else if (!isOpen) {
+ onOpen();
+ if (!hasSearch) {
+ setHighlightedIndex(0);
+ }
+ }
+ break;
+
+ case 'Escape':
+ if (isOpen) {
+ e.preventDefault();
+ closeAndReset();
+ }
+ break;
+
+ case 'Home':
+ e.preventDefault();
+ if (isOpen && enabledIndices.length > 0) {
+ setHighlightedIndex(enabledIndices[0]);
+ }
+ break;
+
+ case 'End':
+ e.preventDefault();
+ if (isOpen && enabledIndices.length > 0) {
+ setHighlightedIndex(enabledIndices[enabledIndices.length - 1]);
+ }
+ break;
+
+ default:
+ // Typeahead only when search is not present
+ if (!hasSearch && e.key.length === 1 && !e.ctrlKey && !e.metaKey) {
+ const newTypeahead = typeahead + e.key.toLowerCase();
+ setTypeahead(newTypeahead);
+
+ if (typeaheadTimeoutRef.current) {
+ clearTimeout(typeaheadTimeoutRef.current);
+ }
+ typeaheadTimeoutRef.current = setTimeout(() => {
+ setTypeahead('');
+ }, 500);
+
+ const matchIndex = selectableItems.findIndex(
+ item =>
+ !item.disabled &&
+ item.label?.toLowerCase().startsWith(newTypeahead),
+ );
+ if (matchIndex >= 0) {
+ if (!isOpen) {
+ onOpen();
+ }
+ setHighlightedIndex(matchIndex);
+ }
+ }
+ break;
+ }
+ },
+ [
+ isDisabled,
+ isOpen,
+ onOpen,
+ closeAndReset,
+ selectableItems,
+ highlightedIndex,
+ onToggle,
+ getEnabledIndices,
+ typeahead,
+ hasSearch,
+ ],
+ );
+
+ return {
+ highlightedIndex,
+ setHighlightedIndex,
+ getItemId,
+ onTriggerClick,
+ onKeyDown,
+ onItemMouseEnter,
+ };
+}
diff --git a/packages/core/src/MultiSelector/index.ts b/packages/core/src/MultiSelector/index.ts
new file mode 100644
index 0000000000..0b80bdeef5
--- /dev/null
+++ b/packages/core/src/MultiSelector/index.ts
@@ -0,0 +1,22 @@
+'use client';
+
+/**
+ * @file index.ts
+ * @output Exports XDSMultiSelector and types
+ * @position Public API entry point
+ */
+
+export {
+ XDSMultiSelector,
+ type XDSMultiSelectorProps,
+ type XDSMultiSelectorSize,
+ type XDSMultiSelectorStatusType,
+} from './XDSMultiSelector';
+export type {
+ XDSMultiSelectorOptionType,
+ XDSMultiSelectorOptionData,
+ XDSMultiSelectorDivider,
+ XDSMultiSelectorSection,
+ XDSMultiSelectorStatus,
+} from './types';
+export {useMultiCombobox} from './hooks';
diff --git a/packages/core/src/MultiSelector/types.ts b/packages/core/src/MultiSelector/types.ts
new file mode 100644
index 0000000000..d7e43bed46
--- /dev/null
+++ b/packages/core/src/MultiSelector/types.ts
@@ -0,0 +1,26 @@
+/**
+ * @file types.ts
+ * @input Imports types from ../Selector/types
+ * @output Re-exports Selector types with MultiSelector aliases
+ * @position Type definitions; used by XDSMultiSelector.tsx and hooks.ts
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/MultiSelector/index.ts
+ */
+
+import type {
+ XDSSelectorOptionData,
+ XDSSelectorDivider,
+ XDSSelectorSection,
+ XDSSelectorOptionType,
+} from '../Selector/types';
+
+export type XDSMultiSelectorOptionData = XDSSelectorOptionData;
+export type XDSMultiSelectorDivider = XDSSelectorDivider;
+export type XDSMultiSelectorSection = XDSSelectorSection;
+export type XDSMultiSelectorOptionType = XDSSelectorOptionType;
+
+export interface XDSMultiSelectorStatus {
+ type: 'warning' | 'error' | 'success';
+ message?: string;
+}
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 82661370f8..67d277e260 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -42,6 +42,7 @@ export * from './Grid';
export * from './Section';
export * from './SegmentedControl';
export * from './Selector';
+export * from './MultiSelector';
export * from './Icon';
export * from './Text';
export * from './TextInput';