` | Floating positioned container |
| `Autocomplete.Popup` | `
` | 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
>;
labelsRef: React.MutableRefObject>;
popupRef: React.RefObject;
+ triggerRef: React.MutableRefObject;
arrowRef: React.MutableRefObject;
valuesByIndexRef: React.MutableRefObject>;
setInlineMode: React.Dispatch>;
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>([]);
const arrowRef = useRef(null);
const popupRef = useRef(null);
+ const triggerRef = useRef(null);
const valuesByIndexRef = useRef>(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(
+ 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) {
+ event.preventDefault();
+ },
+ onClick() {
+ setOpen(!open);
+ focusInput();
+ },
+ } satisfies DefaultProps<'button'>;
+
+ return useRender({
+ defaultTagName: 'button',
+ render,
+ ref: [triggerRef, ref],
+ state,
+ stateAttributesMapping: {
+ open: (value: boolean): Record | 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 {
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(
+
+
+
+
+
+ Apple
+
+
+ ,
+ );
+
+ 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();
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> = {
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.
+
+
+
+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
+
+
+
+
+
+
+
+
+ {countries.map(country => (
+
+ {country.name}
+
+ ))}
+
+
+```
+
+## Scrolling
+
+Long lists receive the shared ScrollArea fade and scrollbar automatically.
+
+
+
+## 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 (
+
+
+ Fruit
+
+
+
+ }
+ >
+
+
+
+
+
+ {filtered.length > 0 ? (
+ filtered.map(option => (
+
+ {option}
+
+ ))
+ ) : (
+ No fruit found
+ )}
+
+
+ );
+}
+
+export function Default() {
+ return ;
+}
+
+const manyFruits = Array.from({ length: 40 }, (_, index) => `Fruit ${index + 1}`);
+
+export function Scrolling() {
+ return ;
+}
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 (
+
+
+
+
+ }
+ >
+
+
+
+
+
+ Apple
+
+
+ Banana
+
+
+
+ );
+}
+
+describe('Mosaic Combobox', () => {
+ it('opens its options from a composed trigger', async () => {
+ const user = userEvent.setup();
+ render();
+
+ 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(
+
+ Fruit
+
+
+
+ Apple
+
+
+ Choose a fruit
+ ,
+ );
+
+ 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();
+
+ 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();
+
+ 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();
+
+ 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(
+
+
+
+
+ Apple
+
+
+ ,
+ );
+
+ 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(
+
+
+
+
+
+
+
+
+ United States
+
+ ,
+ );
+
+ 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(No matches);
+
+ 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(function MosaicComboboxTrigger(
+ { className, style, ...props },
+ ref,
+) {
+ return (
+
+ );
+});
+
+export interface ComboboxInputProps extends Omit, 'size'> {
+ size?: ComboboxSize;
+ variant?: InputVariant;
+}
+
+export const ComboboxInput = React.forwardRef(function MosaicComboboxInput(
+ { size: sizeProp, variant = 'default', render, className, style, ...rest },
+ ref,
+) {
+ const inputGroup = useOptionalInputGroupContext();
+ const size = inputGroup?.size ?? sizeProp ?? 'md';
+
+ return (
+
+ )
+ }
+ {...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['root'];
+}
+
+/** Floating listbox surface. Portal and positioning are handled internally. */
+export const ComboboxPopup = React.forwardRef(function MosaicComboboxPopup(
+ { portalRoot, className, style, children, ...rest },
+ ref,
+) {
+ return (
+
+
+
+
+ {children}
+
+
+
+
+ );
+});
+
+export type ComboboxListProps = MosaicComponentProps<'div'>;
+
+/** Scrollable listbox used when the combobox is embedded in another surface. */
+export const ComboboxList = React.forwardRef(function MosaicComboboxList(
+ { className, style, ...rest },
+ ref,
+) {
+ return (
+
+ );
+});
+
+export interface ComboboxOptionProps extends MosaicComponentProps<'div'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export const ComboboxOption = React.forwardRef(function MosaicComboboxOption(
+ { className, style, ...rest },
+ ref,
+) {
+ return (
+
+ );
+});
+
+export type ComboboxEmptyProps = MosaicComponentProps<'p'>;
+
+export const ComboboxEmpty = React.forwardRef(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,