From 7705087ab7de5f7a70f79b4825b8a5ca5951a4b6 Mon Sep 17 00:00:00 2001
From: austincalvelage <austin.calvelage@icloud.com>
Date: Wed, 2 Sep 2026 18:47:31 -0600
Subject: [PATCH] feat(ui): add combobox

---
 .changeset/calm-combs-search.md               |   2 +
 .../src/primitives/autocomplete/README.md     |   8 +-
 .../autocomplete/autocomplete-context.ts      |   4 +
 .../autocomplete/autocomplete-root.tsx        |  25 ++-
 .../autocomplete/autocomplete-trigger.tsx     |  42 ++++
 .../autocomplete/autocomplete.test.tsx        |  34 +++
 .../src/primitives/autocomplete/parts.ts      |   1 +
 .../swingset/src/components/DocsViewer.tsx    |   1 +
 packages/swingset/src/lib/registry.ts         |  12 +
 packages/swingset/src/stories/combobox.mdx    |  64 ++++++
 .../swingset/src/stories/combobox.stories.tsx |  81 +++++++
 .../components/combobox/combobox.styles.ts    |  92 ++++++++
 .../components/combobox/combobox.test.tsx     | 208 ++++++++++++++++++
 .../mosaic/components/combobox/combobox.tsx   | 167 ++++++++++++++
 .../src/mosaic/components/combobox/index.ts   |  19 ++
 packages/ui/src/mosaic/styles/index.ts        |  10 +
 16 files changed, 767 insertions(+), 3 deletions(-)
 create mode 100644 .changeset/calm-combs-search.md
 create mode 100644 packages/headless/src/primitives/autocomplete/autocomplete-trigger.tsx
 create mode 100644 packages/swingset/src/stories/combobox.mdx
 create mode 100644 packages/swingset/src/stories/combobox.stories.tsx
 create mode 100644 packages/ui/src/mosaic/components/combobox/combobox.styles.ts
 create mode 100644 packages/ui/src/mosaic/components/combobox/combobox.test.tsx
 create mode 100644 packages/ui/src/mosaic/components/combobox/combobox.tsx
 create mode 100644 packages/ui/src/mosaic/components/combobox/index.ts

diff --git a/.changeset/calm-combs-search.md b/.changeset/calm-combs-search.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/calm-combs-search.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/headless/src/primitives/autocomplete/README.md b/packages/headless/src/primitives/autocomplete/README.md
index a0b04ba7968..f643ca3b8ef 100644
--- a/packages/headless/src/primitives/autocomplete/README.md
+++ b/packages/headless/src/primitives/autocomplete/README.md
@@ -25,6 +25,7 @@ function MyAutocomplete() {
       onInputValueChange={setInputValue}
     >
       <Autocomplete.Input placeholder='Search fruits...' />
+      <Autocomplete.Trigger aria-label='Toggle fruit options'>⌄</Autocomplete.Trigger>
       <Autocomplete.Positioner>
         <Autocomplete.Popup>
           {filtered.map(fruit => (
@@ -75,6 +76,7 @@ In this pattern, keep the outer `Popover` or `Dialog` as the source of truth for
 | ------------------------- | --------------- | ---------------------------------------- |
 | `Autocomplete.Root`       | —               | Root context provider                    |
 | `Autocomplete.Input`      | `<input>`       | Text input that drives filtering         |
+| `Autocomplete.Trigger`    | `<button>`      | Pointer-accessible popup toggle          |
 | `Autocomplete.Portal`     | —               | Portals children (accepts `root` prop)   |
 | `Autocomplete.Positioner` | `<div>`         | Floating positioned container            |
 | `Autocomplete.Popup`      | `<div>`         | Visual wrapper for the option list       |
@@ -108,7 +110,7 @@ In this pattern, keep the outer `Popover` or `Dialog` as the source of truth for
 | `label`    | `string`  | falls back to `value` | Display label, also used for input text on selection |
 | `disabled` | `boolean` | —                     | Prevents selection                                   |
 
-### `Autocomplete.Input`, `Autocomplete.Positioner`, `Autocomplete.Popup`, `Autocomplete.List`
+### `Autocomplete.Input`, `Autocomplete.Trigger`, `Autocomplete.Positioner`, `Autocomplete.Popup`, `Autocomplete.List`
 
 No additional props beyond standard HTML attributes and the `render` prop.
 
@@ -131,7 +133,7 @@ Navigation loops and auto-scrolls the active option into view.
 
 | Attribute                   | Applies To        | Description                     |
 | --------------------------- | ----------------- | ------------------------------- |
-| `data-open` / `data-closed` | Input             | Popup open state                |
+| `data-open` / `data-closed` | Input, Trigger    | Popup open state                |
 | `data-selected`             | Option            | The currently selected option   |
 | `data-active`               | Option            | The keyboard-highlighted option |
 | `data-disabled`             | Option            | Disabled option                 |
@@ -140,6 +142,7 @@ Navigation loops and auto-scrolls the active option into view.
 ## Open/Close Behavior
 
 - Typing a non-empty string opens the popup automatically.
+- Activating `Trigger` toggles the popup and returns focus to the input.
 - Clearing the input closes the popup.
 - Clicking an option closes the popup and returns focus to the input.
 - Outside click and Escape close the popup.
@@ -147,5 +150,6 @@ Navigation loops and auto-scrolls the active option into view.
 ## ARIA
 
 - Input: `aria-autocomplete="list"`, `aria-activedescendant` (virtual focus)
+- Trigger: `tabindex="-1"`, `aria-controls`, `aria-expanded`
 - Options: `role="option"`, `aria-selected`, `aria-disabled`
 - Focus manager: non-modal, `initialFocus={-1}` (focus stays on input)
diff --git a/packages/headless/src/primitives/autocomplete/autocomplete-context.ts b/packages/headless/src/primitives/autocomplete/autocomplete-context.ts
index 3fae09aff96..4dd7327e5e0 100644
--- a/packages/headless/src/primitives/autocomplete/autocomplete-context.ts
+++ b/packages/headless/src/primitives/autocomplete/autocomplete-context.ts
@@ -25,11 +25,15 @@ export interface AutocompleteContextValue {
   elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
   labelsRef: React.MutableRefObject<Array<string | null>>;
   popupRef: React.RefObject<HTMLDivElement | null>;
+  triggerRef: React.MutableRefObject<HTMLButtonElement | null>;
   arrowRef: React.MutableRefObject<SVGSVGElement | null>;
   valuesByIndexRef: React.MutableRefObject<Map<number, string>>;
   setInlineMode: React.Dispatch<React.SetStateAction<boolean>>;
   handleSelect: (value: string, index: number, label: string) => void;
   handleInputChange: (value: string) => void;
+  setOpen: (open: boolean) => void;
+  focusInput: () => void;
+  popupId: string | undefined;
   registerSelectedIndex: (index: number, value: string) => void;
   mounted: boolean;
   transitionProps: TransitionProps;
diff --git a/packages/headless/src/primitives/autocomplete/autocomplete-root.tsx b/packages/headless/src/primitives/autocomplete/autocomplete-root.tsx
index daa6f5581d5..32dfe3551cd 100644
--- a/packages/headless/src/primitives/autocomplete/autocomplete-root.tsx
+++ b/packages/headless/src/primitives/autocomplete/autocomplete-root.tsx
@@ -68,6 +68,7 @@ function AutocompleteInner(props: AutocompleteProps) {
   const labelsRef = useRef<Array<string | null>>([]);
   const arrowRef = useRef<SVGSVGElement | null>(null);
   const popupRef = useRef<HTMLDivElement | null>(null);
+  const triggerRef = useRef<HTMLButtonElement | null>(null);
   const valuesByIndexRef = useRef<Map<number, string>>(new Map());
   const registerSelectedIndex = useCallback(
     (index: number, value: string) => {
@@ -125,7 +126,13 @@ function AutocompleteInner(props: AutocompleteProps) {
 
   const dismiss = useDismiss(floatingContext, {
     escapeKey: !inlineMode,
-    outsidePress: !inlineMode,
+    outsidePress(event) {
+      if (inlineMode) {
+        return false;
+      }
+      const target = event.target;
+      return !(target instanceof Node && triggerRef.current?.contains(target));
+    },
     bubbles: {
       escapeKey: inlineMode,
       outsidePress: inlineMode,
@@ -143,6 +150,15 @@ function AutocompleteInner(props: AutocompleteProps) {
   });
 
   const { getReferenceProps, getFloatingProps, getItemProps } = useInteractions([dismiss, role, listNav]);
+  const referenceProps = getReferenceProps();
+  const popupId = typeof referenceProps['aria-controls'] === 'string' ? referenceProps['aria-controls'] : undefined;
+
+  const focusInput = useCallback(() => {
+    const input = refs.domReference.current;
+    if (input instanceof HTMLElement) {
+      input.focus();
+    }
+  }, [refs.domReference]);
 
   const handleSelect = useCallback(
     (value: string, index: number, label: string) => {
@@ -186,11 +202,15 @@ function AutocompleteInner(props: AutocompleteProps) {
       elementsRef,
       labelsRef,
       popupRef,
+      triggerRef,
       arrowRef,
       valuesByIndexRef,
       setInlineMode,
       handleSelect,
       handleInputChange,
+      setOpen,
+      focusInput,
+      popupId,
       registerSelectedIndex,
       mounted,
       transitionProps,
@@ -210,6 +230,9 @@ function AutocompleteInner(props: AutocompleteProps) {
       selectedIndex,
       handleSelect,
       handleInputChange,
+      setOpen,
+      focusInput,
+      popupId,
       registerSelectedIndex,
       mounted,
       transitionProps,
diff --git a/packages/headless/src/primitives/autocomplete/autocomplete-trigger.tsx b/packages/headless/src/primitives/autocomplete/autocomplete-trigger.tsx
new file mode 100644
index 00000000000..d1db84cd724
--- /dev/null
+++ b/packages/headless/src/primitives/autocomplete/autocomplete-trigger.tsx
@@ -0,0 +1,42 @@
+'use client';
+
+import React from 'react';
+
+import { type ComponentProps, type DefaultProps, mergeProps, useRender } from '../../utils';
+import { useAutocompleteContext } from './autocomplete-context';
+
+export type AutocompleteTriggerProps = ComponentProps<'button'>;
+
+export const AutocompleteTrigger = React.forwardRef<HTMLButtonElement, AutocompleteTriggerProps>(
+  function AutocompleteTrigger(props, ref) {
+    const { render, ...otherProps } = props;
+    const { open, setOpen, focusInput, popupId, triggerRef } = useAutocompleteContext();
+    const state = { open };
+
+    const defaultProps = {
+      type: 'button',
+      tabIndex: -1,
+      'aria-controls': popupId,
+      'aria-expanded': open,
+      'aria-haspopup': 'listbox',
+      onPointerDown(event: React.PointerEvent<HTMLButtonElement>) {
+        event.preventDefault();
+      },
+      onClick() {
+        setOpen(!open);
+        focusInput();
+      },
+    } satisfies DefaultProps<'button'>;
+
+    return useRender({
+      defaultTagName: 'button',
+      render,
+      ref: [triggerRef, ref],
+      state,
+      stateAttributesMapping: {
+        open: (value: boolean): Record<string, string> | null => (value ? { 'data-open': '' } : { 'data-closed': '' }),
+      },
+      props: mergeProps<'button'>(defaultProps, otherProps),
+    });
+  },
+);
diff --git a/packages/headless/src/primitives/autocomplete/autocomplete.test.tsx b/packages/headless/src/primitives/autocomplete/autocomplete.test.tsx
index 18066c37bd7..162cd187e47 100644
--- a/packages/headless/src/primitives/autocomplete/autocomplete.test.tsx
+++ b/packages/headless/src/primitives/autocomplete/autocomplete.test.tsx
@@ -78,6 +78,40 @@ function StaticAutocomplete(props: Partial<React.ComponentProps<typeof Autocompl
 
 describe('Autocomplete', () => {
   describe('open/close', () => {
+    it('toggles from a popup button while keeping focus on the input', async () => {
+      const user = userEvent.setup();
+      const onOpenChange = vi.fn();
+      render(
+        <Autocomplete.Root onOpenChange={onOpenChange}>
+          <Autocomplete.Input placeholder='Search fruits...' />
+          <Autocomplete.Trigger aria-label='Toggle fruit options' />
+          <Autocomplete.Positioner>
+            <Autocomplete.Popup>
+              <Autocomplete.Option value='apple'>Apple</Autocomplete.Option>
+            </Autocomplete.Popup>
+          </Autocomplete.Positioner>
+        </Autocomplete.Root>,
+      );
+
+      const input = screen.getByRole('combobox');
+      const trigger = screen.getByRole('button', { name: 'Toggle fruit options' });
+      expect(trigger).toHaveAttribute('tabindex', '-1');
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+
+      await user.click(trigger);
+
+      const listbox = screen.getByRole('listbox');
+      expect(trigger).toHaveAttribute('aria-expanded', 'true');
+      expect(trigger).toHaveAttribute('aria-controls', listbox.id);
+      expect(input).toHaveFocus();
+
+      await user.click(trigger);
+
+      expect(onOpenChange).toHaveBeenLastCalledWith(false);
+      expect(trigger).toHaveAttribute('aria-expanded', 'false');
+      expect(input).toHaveFocus();
+    });
+
     it('opens when user types', async () => {
       const user = userEvent.setup();
       render(<FilteredAutocomplete />);
diff --git a/packages/headless/src/primitives/autocomplete/parts.ts b/packages/headless/src/primitives/autocomplete/parts.ts
index 8d184c6c6d3..c3246fee40a 100644
--- a/packages/headless/src/primitives/autocomplete/parts.ts
+++ b/packages/headless/src/primitives/autocomplete/parts.ts
@@ -1,5 +1,6 @@
 export { type AutocompleteProps, AutocompleteRoot as Root } from './autocomplete-root';
 export { type AutocompleteInputProps, AutocompleteInput as Input } from './autocomplete-input';
+export { type AutocompleteTriggerProps, AutocompleteTrigger as Trigger } from './autocomplete-trigger';
 export { type AutocompletePortalProps, AutocompletePortal as Portal } from './autocomplete-portal';
 export { type AutocompletePositionerProps, AutocompletePositioner as Positioner } from './autocomplete-positioner';
 export { type AutocompletePopupProps, AutocompletePopup as Popup } from './autocomplete-popup';
diff --git a/packages/swingset/src/components/DocsViewer.tsx b/packages/swingset/src/components/DocsViewer.tsx
index 739d1d2ae84..946a1014ae1 100644
--- a/packages/swingset/src/components/DocsViewer.tsx
+++ b/packages/swingset/src/components/DocsViewer.tsx
@@ -47,6 +47,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     banner: dynamic(() => import('../stories/banner.mdx')),
     button: dynamic(() => import('../stories/button.mdx')),
     card: dynamic(() => import('../stories/card.component.mdx')),
+    combobox: dynamic(() => import('../stories/combobox.mdx')),
     input: dynamic(() => import('../stories/input.mdx')),
     'input-group': dynamic(() => import('../stories/input-group.mdx')),
     item: dynamic(() => import('../stories/item.mdx')),
diff --git a/packages/swingset/src/lib/registry.ts b/packages/swingset/src/lib/registry.ts
index f0cd41eeba8..dabdff44286 100644
--- a/packages/swingset/src/lib/registry.ts
+++ b/packages/swingset/src/lib/registry.ts
@@ -25,6 +25,11 @@ import {
 import { Disabled, meta as buttonMeta, Primary, Sizes } from '../stories/button.stories';
 import { Default as CardDefault, meta as cardComponentMeta } from '../stories/card.component.stories';
 import { meta as collapsibleMeta } from '../stories/collapsible.stories';
+import {
+  Default as ComboboxDefault,
+  meta as comboboxMeta,
+  Scrolling as ComboboxScrolling,
+} from '../stories/combobox.stories';
 import {
   Default as DestructiveDefault,
   meta as destructiveMeta,
@@ -243,6 +248,12 @@ const dialogComponentModule: StoryModule = { meta: dialogComponentMeta, Default:
 
 const cardComponentModule: StoryModule = { meta: cardComponentMeta, Default: CardDefault };
 
+const comboboxModule: StoryModule = {
+  meta: comboboxMeta,
+  Default: ComboboxDefault,
+  Scrolling: ComboboxScrolling,
+};
+
 const avatarModule: StoryModule = {
   meta: avatarMeta,
   Primary: AvatarPrimary,
@@ -521,6 +532,7 @@ export const registry: StoryModule[] = [
   bannerModule,
   buttonModule,
   cardComponentModule,
+  comboboxModule,
   flowComponentModule,
   inputModule,
   inputGroupModule,
diff --git a/packages/swingset/src/stories/combobox.mdx b/packages/swingset/src/stories/combobox.mdx
new file mode 100644
index 00000000000..6a0cb63ce2d
--- /dev/null
+++ b/packages/swingset/src/stories/combobox.mdx
@@ -0,0 +1,64 @@
+import * as ComboboxStories from './combobox.stories';
+
+# Combobox
+
+`Combobox` adds Mosaic styling to the headless `Autocomplete` behavior: text entry, listbox ARIA,
+keyboard navigation, selection, positioning, and the shared scrolling treatment.
+
+## Example
+
+Use the trigger to show every option, or type to open and filter the list. Use the arrow keys and
+Enter to select an option.
+
+<Story
+  name='Default'
+  storyModule={ComboboxStories}
+/>
+
+Filtering stays with the caller: read `inputValue` and render only the matching options.
+`Combobox.Popup` owns its portal, positioner, surface, and scrolling viewport.
+
+## Inline lists
+
+Use `List` when the searchable list already lives in another floating surface, such as a country
+picker inside a popover. Use the headless input variant when it needs an icon or adjacent text.
+This avoids both a second input implementation and a nested popup.
+
+```tsx
+<Combobox.Root open inputValue={query} onInputValueChange={setQuery}>
+  <InputGroup.Root>
+    <InputGroup.Text>
+      <Icon name='search' aria-hidden='true' />
+    </InputGroup.Text>
+    <Combobox.Input variant='headless' aria-label='Search countries' />
+  </InputGroup.Root>
+  <Combobox.List>
+    {countries.map(country => (
+      <Combobox.Option key={country.iso} value={country.iso} label={country.name}>
+        {country.name}
+      </Combobox.Option>
+    ))}
+  </Combobox.List>
+</Combobox.Root>
+```
+
+## Scrolling
+
+Long lists receive the shared ScrollArea fade and scrollbar automatically.
+
+<Story
+  name='Scrolling'
+  storyModule={ComboboxStories}
+/>
+
+## Parts
+
+| Part               | Description                                                                       |
+| ------------------ | --------------------------------------------------------------------------------- |
+| `Combobox.Root`    | Owns input, selection, open state, and keyboard navigation.                       |
+| `Combobox.Input`   | Autocomplete input; renders Mosaic `Input` unless composed through another input. |
+| `Combobox.Trigger` | Opens and closes the option list while keeping focus on the input.                |
+| `Combobox.Popup`   | Portals, positions, surfaces, and scrolls a floating option list.                 |
+| `Combobox.List`    | Scrollable inline listbox.                                                        |
+| `Combobox.Option`  | Selectable option with active, selected, and disabled states.                     |
+| `Combobox.Empty`   | Empty result message.                                                             |
diff --git a/packages/swingset/src/stories/combobox.stories.tsx b/packages/swingset/src/stories/combobox.stories.tsx
new file mode 100644
index 00000000000..f1681377da2
--- /dev/null
+++ b/packages/swingset/src/stories/combobox.stories.tsx
@@ -0,0 +1,81 @@
+'use client';
+
+import { Combobox } from '@clerk/ui/mosaic/components/combobox';
+import { Field } from '@clerk/ui/mosaic/components/field';
+import { Icon } from '@clerk/ui/mosaic/components/icon';
+import { InputGroup } from '@clerk/ui/mosaic/components/input-group';
+import { useState } from 'react';
+
+import type { StoryMeta } from '@/lib/types';
+
+export { default as __source } from './combobox.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'Combobox',
+  source: 'packages/ui/src/mosaic/components/combobox/combobox.tsx',
+};
+
+const fruits = ['Apple', 'Apricot', 'Banana', 'Blackberry', 'Cherry', 'Fig', 'Grape', 'Pear', 'Plum'];
+
+function FruitCombobox({ options = fruits }: { options?: string[] }) {
+  const [query, setQuery] = useState('');
+  const filtered = options.filter(option => option.toLowerCase().includes(query.toLowerCase()));
+
+  return (
+    <Combobox.Root
+      inputValue={query}
+      onInputValueChange={setQuery}
+    >
+      <Field.Root style={{ width: 320 }}>
+        <Field.Label>Fruit</Field.Label>
+        <InputGroup.Root>
+          <Combobox.Input
+            variant='headless'
+            placeholder='Search fruit…'
+          />
+          <Combobox.Trigger
+            aria-label='Toggle fruit options'
+            render={
+              <InputGroup.Action
+                size='xs'
+                shape='square'
+              />
+            }
+          >
+            <Icon
+              name='chevron-down'
+              size='sm'
+              aria-hidden='true'
+            />
+          </Combobox.Trigger>
+        </InputGroup.Root>
+      </Field.Root>
+      <Combobox.Popup>
+        {filtered.length > 0 ? (
+          filtered.map(option => (
+            <Combobox.Option
+              key={option}
+              value={option.toLowerCase()}
+              label={option}
+            >
+              {option}
+            </Combobox.Option>
+          ))
+        ) : (
+          <Combobox.Empty>No fruit found</Combobox.Empty>
+        )}
+      </Combobox.Popup>
+    </Combobox.Root>
+  );
+}
+
+export function Default() {
+  return <FruitCombobox />;
+}
+
+const manyFruits = Array.from({ length: 40 }, (_, index) => `Fruit ${index + 1}`);
+
+export function Scrolling() {
+  return <FruitCombobox options={manyFruits} />;
+}
diff --git a/packages/ui/src/mosaic/components/combobox/combobox.styles.ts b/packages/ui/src/mosaic/components/combobox/combobox.styles.ts
new file mode 100644
index 00000000000..df38efa4c4b
--- /dev/null
+++ b/packages/ui/src/mosaic/components/combobox/combobox.styles.ts
@@ -0,0 +1,92 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, fontFamilyVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+export const styles = stylex.create({
+  positioner: {
+    outline: 'none',
+  },
+  popup: {
+    borderRadius: radiusVars['--cl-radius-lg'],
+    outline: 'none',
+    overflow: 'hidden',
+    backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px light-dark(oklch(0.2046 0 0 / 12%), transparent),
+                0 24px 24px -10px light-dark(oklch(0.2046 0 0 / 4%), transparent),
+                0 0 0 1px light-dark(oklch(0.2046 0 0 / 4%), oklch(1 0 0 / 10%))`,
+    color: colorVars['--cl-color-card-foreground'],
+    opacity: {
+      default: 1,
+      ':where([data-ending-style], [data-starting-style])': 0,
+    },
+    scale: {
+      default: 1,
+      ':where([data-ending-style], [data-starting-style])': 0.96,
+    },
+    transformOrigin: 'var(--cl-transform-origin)',
+    transitionDuration: {
+      default: '150ms',
+      '@media (prefers-reduced-motion: reduce)': '0.01ms',
+    },
+    transitionProperty: 'opacity, scale',
+    transitionTimingFunction: 'ease-out',
+    maxHeight: 'var(--cl-available-height)',
+    minWidth: '12.5rem',
+  },
+  viewport: {
+    padding: space['1'],
+    gap: space['0.5'],
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: '16rem',
+  },
+  list: {
+    padding: space['1'],
+    gap: space['0.5'],
+    display: 'flex',
+    flexDirection: 'column',
+    maxHeight: '16rem',
+  },
+  option: {
+    borderRadius: radiusVars['--cl-radius-md'],
+    gap: space['2'],
+    outline: {
+      default: 'none',
+      '@media (forced-colors: active)': {
+        default: null,
+        ':is([data-active])': '2px solid CanvasText',
+      },
+    },
+    paddingInline: space['2'],
+    alignItems: 'center',
+    backgroundColor: {
+      default: 'transparent',
+      ':is([data-active])': `color-mix(in oklab, ${colorVars['--cl-color-neutral']} 4%, transparent)`,
+      '@media (hover: hover)': {
+        ':hover': `color-mix(in oklab, ${colorVars['--cl-color-neutral']} 4%, transparent)`,
+      },
+    },
+    cursor: {
+      default: 'pointer',
+      ':is([data-disabled])': 'not-allowed',
+    },
+    display: 'flex',
+    flexShrink: 0,
+    fontFamily: fontFamilyVars['--cl-font-family-sans'],
+    fontSize: typeScaleVars['--cl-text-sm-size'],
+    fontWeight: fontWeightVars['--cl-font-medium'],
+    opacity: {
+      default: 1,
+      ':is([data-disabled])': 0.5,
+    },
+    height: space['9'],
+  },
+  empty: {
+    paddingBlock: space['6'],
+    paddingInline: space['3'],
+    color: colorVars['--cl-color-neutral-faded'],
+    fontFamily: fontFamilyVars['--cl-font-family-sans'],
+    fontSize: typeScaleVars['--cl-text-sm-size'],
+    textAlign: 'center',
+  },
+});
diff --git a/packages/ui/src/mosaic/components/combobox/combobox.test.tsx b/packages/ui/src/mosaic/components/combobox/combobox.test.tsx
new file mode 100644
index 00000000000..5e13467720f
--- /dev/null
+++ b/packages/ui/src/mosaic/components/combobox/combobox.test.tsx
@@ -0,0 +1,208 @@
+import * as stylex from '@stylexjs/stylex';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import React from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import { Field } from '../field';
+import { Icon } from '../icon';
+import { InputGroup } from '../input-group';
+import { scrollAreaRoot, scrollAreaViewport } from '../scroll-area';
+import { Combobox } from './combobox';
+
+const scrollClasses = stylex.props(...scrollAreaViewport()).className?.split(' ') ?? [];
+const rootClasses = stylex.props(scrollAreaRoot).className?.split(' ') ?? [];
+const viewportOnlyClasses = scrollClasses.filter(name => !rootClasses.includes(name));
+
+function FloatingCombobox(props?: { onValueChange?: (value: string) => void }) {
+  return (
+    <Combobox.Root onValueChange={props?.onValueChange}>
+      <InputGroup.Root>
+        <Combobox.Input
+          variant='headless'
+          aria-label='Fruit'
+          placeholder='Search fruit'
+        />
+        <Combobox.Trigger
+          aria-label='Toggle fruit options'
+          render={
+            <InputGroup.Action
+              size='xs'
+              shape='square'
+            />
+          }
+        >
+          <Icon
+            name='chevron-down'
+            size='sm'
+            aria-hidden='true'
+          />
+        </Combobox.Trigger>
+      </InputGroup.Root>
+      <Combobox.Popup>
+        <Combobox.Option
+          value='apple'
+          label='Apple'
+        >
+          Apple
+        </Combobox.Option>
+        <Combobox.Option
+          value='banana'
+          label='Banana'
+        >
+          Banana
+        </Combobox.Option>
+      </Combobox.Popup>
+    </Combobox.Root>
+  );
+}
+
+describe('Mosaic Combobox', () => {
+  it('opens its options from a composed trigger', async () => {
+    const user = userEvent.setup();
+    render(<FloatingCombobox />);
+
+    const input = screen.getByRole('combobox', { name: 'Fruit' });
+    const trigger = screen.getByRole('button', { name: 'Toggle fruit options' });
+    expect(trigger).toHaveClass('cl-button', 'cl-input-group-action', 'cl-combobox-trigger');
+    expect(trigger).toHaveAttribute('data-size', 'xs');
+    expect(trigger).toHaveAttribute('data-variant', 'ghost');
+    expect(trigger).toHaveAttribute('data-color', 'neutral');
+
+    await user.click(trigger);
+
+    expect(screen.getByRole('listbox')).toBeInTheDocument();
+    expect(trigger).toHaveAttribute('data-open', '');
+    expect(input).toHaveFocus();
+  });
+
+  it('renders a field-aware, sized input', () => {
+    render(
+      <Field.Root
+        required
+        invalid
+      >
+        <Field.Label>Fruit</Field.Label>
+        <Combobox.Root>
+          <Combobox.Input size='lg' />
+          <Combobox.Popup>
+            <Combobox.Option value='apple'>Apple</Combobox.Option>
+          </Combobox.Popup>
+        </Combobox.Root>
+        <Field.Error>Choose a fruit</Field.Error>
+      </Field.Root>,
+    );
+
+    const input = screen.getByRole('combobox', { name: 'Fruit' });
+    expect(input).toHaveClass('cl-input', 'cl-combobox-input');
+    expect(input).toHaveAttribute('data-size', 'lg');
+    expect(input).toBeRequired();
+    expect(input).toHaveAttribute('aria-invalid', 'true');
+    expect(input).toHaveAccessibleDescription('Choose a fruit');
+  });
+
+  it('opens a styled floating popup when the user types', async () => {
+    const user = userEvent.setup();
+    render(<FloatingCombobox />);
+
+    await user.type(screen.getByRole('combobox', { name: 'Fruit' }), 'a');
+
+    const listbox = screen.getByRole('listbox');
+    const popup = listbox.querySelector('.cl-combobox-popup');
+    const viewport = popup?.querySelector('.cl-combobox-viewport');
+    expect(listbox).toHaveClass('cl-combobox-positioner');
+    expect(popup).toBeInTheDocument();
+    expect(viewport).toHaveClass(...scrollClasses);
+    expect(viewportOnlyClasses).not.toHaveLength(0);
+    expect(viewportOnlyClasses.filter(name => popup?.classList.contains(name))).toEqual([]);
+    expect(screen.getByRole('option', { name: 'Apple' }).closest('.cl-combobox-viewport')).toBe(viewport);
+  });
+
+  it('selects an option and restores its label to the input', async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<FloatingCombobox onValueChange={onValueChange} />);
+
+    const input = screen.getByRole('combobox', { name: 'Fruit' });
+    await user.type(input, 'b');
+    await user.click(screen.getByRole('option', { name: 'Banana' }));
+
+    expect(onValueChange).toHaveBeenCalledWith('banana');
+    expect(input).toHaveValue('Banana');
+    expect(input).toHaveFocus();
+  });
+
+  it('supports keyboard selection', async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(<FloatingCombobox onValueChange={onValueChange} />);
+
+    const input = screen.getByRole('combobox', { name: 'Fruit' });
+    await user.type(input, 'a');
+    await user.keyboard('{Enter}');
+
+    expect(onValueChange).toHaveBeenCalledWith('apple');
+  });
+
+  it('styles disabled options and prevents their selection', async () => {
+    const onValueChange = vi.fn();
+    const user = userEvent.setup();
+    render(
+      <Combobox.Root
+        open
+        onValueChange={onValueChange}
+      >
+        <Combobox.Input aria-label='Fruit' />
+        <Combobox.Popup>
+          <Combobox.Option
+            value='apple'
+            disabled
+          >
+            Apple
+          </Combobox.Option>
+        </Combobox.Popup>
+      </Combobox.Root>,
+    );
+
+    const option = screen.getByRole('option', { name: 'Apple' });
+    expect(option).toHaveClass('cl-combobox-option');
+    expect(option).toHaveAttribute('aria-disabled', 'true');
+    await user.click(option);
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it('uses the headless Input variant inside an input group', () => {
+    render(
+      <Combobox.Root open>
+        <InputGroup.Root size='lg'>
+          <InputGroup.Text>
+            <Icon
+              name='search'
+              aria-hidden='true'
+            />
+          </InputGroup.Text>
+          <Combobox.Input
+            variant='headless'
+            aria-label='Search countries'
+            placeholder='Search country or code'
+          />
+        </InputGroup.Root>
+        <Combobox.List>
+          <Combobox.Option value='us'>United States</Combobox.Option>
+        </Combobox.List>
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole('combobox', { name: 'Search countries' })).toHaveClass('cl-input', 'cl-combobox-input');
+    expect(screen.getByRole('combobox', { name: 'Search countries' })).toHaveAttribute('data-size', 'lg');
+    expect(screen.getByRole('combobox', { name: 'Search countries' })).toHaveAttribute('data-variant', 'headless');
+    expect(screen.getByRole('listbox')).toHaveClass('cl-combobox-list', ...scrollClasses);
+    expect(screen.getByRole('option', { name: 'United States' })).toHaveClass('cl-combobox-option');
+  });
+
+  it('renders a reusable empty state', () => {
+    render(<Combobox.Empty>No matches</Combobox.Empty>);
+
+    expect(screen.getByText('No matches')).toHaveClass('cl-combobox-empty');
+  });
+});
diff --git a/packages/ui/src/mosaic/components/combobox/combobox.tsx b/packages/ui/src/mosaic/components/combobox/combobox.tsx
new file mode 100644
index 00000000000..cb38133673b
--- /dev/null
+++ b/packages/ui/src/mosaic/components/combobox/combobox.tsx
@@ -0,0 +1,167 @@
+'use client';
+
+import type { AutocompleteProps } from '@clerk/headless/autocomplete';
+import { Autocomplete as Primitive } from '@clerk/headless/autocomplete';
+import { useRender } from '@clerk/headless/utils';
+import * as stylex from '@stylexjs/stylex';
+import React from 'react';
+
+import type { MosaicComponentProps } from '../../props';
+import { mergeStyleProps, themeProps } from '../../props';
+import { reset } from '../../utils/reset.styles';
+import { Input, type InputVariant } from '../input';
+import { useOptionalInputGroupContext } from '../input-group/input-group.context';
+import { scrollAreaRoot, scrollAreaViewport } from '../scroll-area';
+import { styles } from './combobox.styles';
+
+export type ComboboxRootProps = AutocompleteProps;
+export type ComboboxSize = 'sm' | 'md' | 'lg';
+export type ComboboxTriggerProps = MosaicComponentProps<'button'>;
+
+export const ComboboxTrigger = React.forwardRef<HTMLButtonElement, ComboboxTriggerProps>(function MosaicComboboxTrigger(
+  { className, style, ...props },
+  ref,
+) {
+  return (
+    <Primitive.Trigger
+      ref={ref}
+      {...mergeStyleProps(themeProps('combobox-trigger'), className, style)}
+      {...props}
+    />
+  );
+});
+
+export interface ComboboxInputProps extends Omit<MosaicComponentProps<'input'>, 'size'> {
+  size?: ComboboxSize;
+  variant?: InputVariant;
+}
+
+export const ComboboxInput = React.forwardRef<HTMLInputElement, ComboboxInputProps>(function MosaicComboboxInput(
+  { size: sizeProp, variant = 'default', render, className, style, ...rest },
+  ref,
+) {
+  const inputGroup = useOptionalInputGroupContext();
+  const size = inputGroup?.size ?? sizeProp ?? 'md';
+
+  return (
+    <Primitive.Input
+      ref={ref}
+      render={
+        render ?? (
+          <Input
+            size={size}
+            variant={variant}
+          />
+        )
+      }
+      {...mergeStyleProps(themeProps('combobox-input', { size, variant }), className, style)}
+      {...rest}
+    />
+  );
+});
+
+export interface ComboboxPopupProps extends MosaicComponentProps<'div'> {
+  /** Container the combobox portals into. Defaults to `document.body`. */
+  portalRoot?: React.ComponentPropsWithoutRef<typeof Primitive.Portal>['root'];
+}
+
+/** Floating listbox surface. Portal and positioning are handled internally. */
+export const ComboboxPopup = React.forwardRef<HTMLDivElement, ComboboxPopupProps>(function MosaicComboboxPopup(
+  { portalRoot, className, style, children, ...rest },
+  ref,
+) {
+  return (
+    <Primitive.Portal root={portalRoot}>
+      <Primitive.Positioner
+        {...mergeStyleProps(themeProps('combobox-positioner'), stylex.props(reset.base, styles.positioner))}
+      >
+        <Primitive.Popup
+          ref={ref}
+          {...mergeStyleProps(
+            themeProps('combobox-popup'),
+            stylex.props(reset.base, scrollAreaRoot, styles.popup),
+            className,
+            style,
+          )}
+          {...rest}
+        >
+          <div
+            {...mergeStyleProps(
+              themeProps('combobox-viewport'),
+              stylex.props(reset.base, ...scrollAreaViewport(), styles.viewport),
+            )}
+          >
+            {children}
+          </div>
+        </Primitive.Popup>
+      </Primitive.Positioner>
+    </Primitive.Portal>
+  );
+});
+
+export type ComboboxListProps = MosaicComponentProps<'div'>;
+
+/** Scrollable listbox used when the combobox is embedded in another surface. */
+export const ComboboxList = React.forwardRef<HTMLDivElement, ComboboxListProps>(function MosaicComboboxList(
+  { className, style, ...rest },
+  ref,
+) {
+  return (
+    <Primitive.List
+      ref={ref}
+      {...mergeStyleProps(
+        themeProps('combobox-list'),
+        stylex.props(reset.base, scrollAreaRoot, ...scrollAreaViewport(), styles.list),
+        className,
+        style,
+      )}
+      {...rest}
+    />
+  );
+});
+
+export interface ComboboxOptionProps extends MosaicComponentProps<'div'> {
+  value: string;
+  label?: string;
+  disabled?: boolean;
+}
+
+export const ComboboxOption = React.forwardRef<HTMLDivElement, ComboboxOptionProps>(function MosaicComboboxOption(
+  { className, style, ...rest },
+  ref,
+) {
+  return (
+    <Primitive.Option
+      ref={ref}
+      {...mergeStyleProps(themeProps('combobox-option'), stylex.props(reset.base, styles.option), className, style)}
+      {...rest}
+    />
+  );
+});
+
+export type ComboboxEmptyProps = MosaicComponentProps<'p'>;
+
+export const ComboboxEmpty = React.forwardRef<HTMLParagraphElement, ComboboxEmptyProps>(function MosaicComboboxEmpty(
+  { render, className, style, ...rest },
+  ref,
+) {
+  return useRender({
+    defaultTagName: 'p',
+    render,
+    ref,
+    props: {
+      ...mergeStyleProps(themeProps('combobox-empty'), stylex.props(reset.base, styles.empty), className, style),
+      ...rest,
+    },
+  });
+});
+
+export const Combobox = {
+  Root: Primitive.Root,
+  Input: ComboboxInput,
+  Trigger: ComboboxTrigger,
+  Popup: ComboboxPopup,
+  List: ComboboxList,
+  Option: ComboboxOption,
+  Empty: ComboboxEmpty,
+};
diff --git a/packages/ui/src/mosaic/components/combobox/index.ts b/packages/ui/src/mosaic/components/combobox/index.ts
new file mode 100644
index 00000000000..27d3254b345
--- /dev/null
+++ b/packages/ui/src/mosaic/components/combobox/index.ts
@@ -0,0 +1,19 @@
+export {
+  Combobox,
+  ComboboxEmpty,
+  ComboboxInput,
+  ComboboxList,
+  ComboboxOption,
+  ComboboxPopup,
+  ComboboxTrigger,
+} from './combobox';
+export type {
+  ComboboxEmptyProps,
+  ComboboxInputProps,
+  ComboboxListProps,
+  ComboboxOptionProps,
+  ComboboxPopupProps,
+  ComboboxRootProps,
+  ComboboxSize,
+  ComboboxTriggerProps,
+} from './combobox';
diff --git a/packages/ui/src/mosaic/styles/index.ts b/packages/ui/src/mosaic/styles/index.ts
index f6867c1723b..28695af5cfb 100644
--- a/packages/ui/src/mosaic/styles/index.ts
+++ b/packages/ui/src/mosaic/styles/index.ts
@@ -24,6 +24,16 @@ export { Button, SubmitButton } from '../components/button';
 export type { ButtonProps, SpinDelayOptions, SubmitButtonProps } from '../components/button';
 export { Card } from '../components/card';
 export type { CardProps } from '../components/card';
+export { Combobox } from '../components/combobox';
+export type {
+  ComboboxEmptyProps,
+  ComboboxInputProps,
+  ComboboxListProps,
+  ComboboxOptionProps,
+  ComboboxPopupProps,
+  ComboboxRootProps,
+  ComboboxSize,
+} from '../components/combobox';
 export { Dialog, createConfirmHandle, useConfirmedClose } from '../components/dialog';
 export type {
   ConfirmHandle,