mui / mui/base-ui

[combobox] Combobox.Root typing/docs reject autoHighlight="always" although runtime supports it

Open
#4,188 10 comments 1 reaction 0 assignees View on GitHub
component: combobox
Dominant language
TypeScript
Stars
10.9k
Forks
543
Avg merge
1d 20h
Merged PRs (30d)
101

Description

# Bug report

## Current behavior

`Combobox.Root` runtime behavior supports `autoHighlight="always"` (works correctly for async search lists), but TypeScript and docs currently reject/omit it.
- In internal combobox engine (AriaCombobox) found [here](https://github.com/mui/base-ui/blob/master/packages/react/src/combobox/root/AriaCombobox.tsx) , `autoHighlight` is typed as `boolean | 'input-change' | 'always'` and runtime logic handles `"always"`.
- In public `Combobox.Root` props, `autoHighlight` is typed as `boolean` only.
- The docs API reference for Combobox Root also shows `boolean` only.
This causes valid runtime usage to fail type-checking.

## Expected behavior

`Combobox.Root` public type and docs should allow `autoHighlight="always"` (matching runtime/internal behavior), so async search use cases can use it without local type workarounds.

## Reproducible example

Minimal repro:
```typescript
import { Combobox } from "@base-ui/react/combobox";
item.label}
autoHighlight="always"
/>;
```
TypeScript error today:
Type '"always"' is not assignable to type 'boolean | undefined'.

## Base UI version

@base-ui/react@1.1.0 but also latest and in docs

## Which browser are you using?

Chrome

## Which OS are you using?

Mac OS

## Which assistive tech are you using (if applicable)?

N/A

## Additional context
Related history:
- Feature issue: #2922
- Merged implementation PR: #2976 (autoHighlight: "always" support)

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.