feat(combobox): add autoHighlight prop

Author: maxffarrell

.changeset/quiet-comboboxes-highlight.md

@@ -0,0 +1,5 @@
+---
+"bits-ui": patch
+---
+
+feat(Combobox): add `autoHighlight` prop

docs/content/components/combobox.md

@@ -349,6 +349,8 @@ To prevent the user from scrolling outside of the `Combobox.Content` component w
 
 The Combobox component follows the [WAI-ARIA descendant pattern](https://www.w3.org/TR/wai-aria-practices-1.2/#combobox) for highlighting items. This means that the `Combobox.Input` retains focus the entire time, even when navigating with the keyboard, and items are highlighted as the user navigates them.
 
+Use the `autoHighlight` prop on `Combobox.Root` to automatically highlight the first matching item after the user filters the list.
+
 ### Styling Highlighted Items
 
 You can use the `data-highlighted` attribute on the `Combobox.Item` component to style the item differently when it is highlighted.

docs/src/lib/content/api-reference/combobox.api.ts

@@ -120,6 +120,11 @@ export const root = defineComponentApiSchema<ComboboxRootPropsWithoutHTML>({
 			description:
 				"Whether or not the user can deselect the selected item by pressing it in a single select.",
 		}),
+		autoHighlight: defineBooleanProp({
+			default: false,
+			description:
+				"Whether or not the first matching item should be highlighted automatically as the user filters the list.",
+		}),
 		items: defineComponentPropSchema({
 			definition: ItemsProp,
 			stringDefinition: `{ value: string; label: string; disabled?: boolean}[]`,

packages/bits-ui/src/lib/bits/combobox/components/combobox.svelte

@@ -21,6 +21,7 @@
 		required = false,
 		items = [],
 		allowDeselect = true,
+		autoHighlight = false,
 		inputValue = "",
 		children,
 	}: ComboboxRootProps = $props();
@@ -63,6 +64,7 @@
 		isCombobox: true,
 		items: boxWith(() => items),
 		allowDeselect: boxWith(() => allowDeselect),
+		autoHighlight: boxWith(() => autoHighlight),
 		inputValue: boxWith(
 			() => inputValue,
 			(v) => (inputValue = v)

packages/bits-ui/src/lib/bits/combobox/types.ts

@@ -10,6 +10,14 @@ export type ComboboxBaseRootPropsWithoutHTML = Omit<
 	SelectBaseRootPropsWithoutHTML,
 	"autocomplete"
 > & {
+	/**
+	 * Whether the first matching item should be highlighted automatically as the
+	 * user filters the list.
+	 *
+	 * @default false
+	 */
+	autoHighlight?: boolean;
+
 	/**
 	 * A read-only value that can be used to programmatically
 	 * update the input value.

packages/bits-ui/src/lib/bits/select/select.svelte.ts

@@ -84,6 +84,7 @@ interface SelectBaseRootStateOpts
 			scrollAlignment: "nearest" | "center";
 			items: { value: string; label: string; disabled?: boolean }[];
 			allowDeselect: boolean;
+			autoHighlight: boolean;
 			onOpenChangeComplete: OnChangeFn<boolean>;
 		}>,
 		WritableBoxedValues<{
@@ -234,6 +235,10 @@ abstract class SelectBaseRootState {
 	getBitsAttr: typeof selectAttrs.getAttr = (part) => {
 		return selectAttrs.getAttr(part, this.isCombobox ? "combobox" : undefined);
 	};
+
+	shouldAutoHighlightAfterInput() {
+		return this.isCombobox && this.opts.autoHighlight.current;
+	}
 }
 
 interface SelectSingleRootStateOpts
@@ -298,6 +303,7 @@ export class SelectSingleRootState extends SelectBaseRootState {
 
 	setInitialHighlightedNode() {
 		afterTick(() => {
+			if (this.shouldAutoHighlightAfterInput()) return;
 			if (
 				this.highlightedNode &&
 				this.domContext.getDocument().contains(this.highlightedNode)
@@ -362,6 +368,7 @@ class SelectMultipleRootState extends SelectBaseRootState {
 
 	setInitialHighlightedNode() {
 		afterTick(() => {
+			if (this.shouldAutoHighlightAfterInput()) return;
 			if (!this.domContext) return;
 			if (
 				this.highlightedNode &&
@@ -399,16 +406,18 @@ interface SelectRootStateOpts
 	isCombobox: boolean;
 	type: "single" | "multiple";
 	value: Box<string> | Box<string[]>;
+	autoHighlight?: Box<boolean>;
 }
 
 export class SelectRootState {
 	static create(props: SelectRootStateOpts): SelectRoot {
-		const { type, ...rest } = props;
+		const { type, autoHighlight = boxWith(() => false), ...rest } = props;
+		const rootProps = { ...rest, autoHighlight };
 
 		const rootState =
 			type === "single"
-				? new SelectSingleRootState(rest as SelectSingleRootStateOpts)
-				: new SelectMultipleRootState(rest as SelectMultipleRootStateOpts);
+				? new SelectSingleRootState(rootProps as SelectSingleRootStateOpts)
+				: new SelectMultipleRootState(rootProps as SelectMultipleRootStateOpts);
 
 		return SelectRootContext.set(rootState);
 	}
@@ -636,7 +645,11 @@ export class SelectInputState {
 
 	oninput(e: BitsEvent<Event, HTMLInputElement>) {
 		this.root.opts.inputValue.current = e.currentTarget.value;
-		this.root.setHighlightedToFirstCandidate();
+		if (this.root.shouldAutoHighlightAfterInput()) {
+			afterTick(() => this.root.setHighlightedToFirstCandidate());
+		} else {
+			this.root.setHighlightedToFirstCandidate();
+		}
 	}
 
 	readonly props = $derived.by(

tests/src/tests/browser-utils.ts

@@ -86,6 +86,21 @@ export async function expectExists(loc: Locator) {
 	await expect.element(loc).toBeInTheDocument();
 }
 
+export async function pointerDown(loc: Locator, init: PointerEventInit = {}) {
+	loc.element().dispatchEvent(
+		new PointerEvent("pointerdown", {
+			bubbles: true,
+			cancelable: true,
+			button: 0,
+			buttons: 1,
+			pointerId: 1,
+			pointerType: "mouse",
+			isPrimary: true,
+			...init,
+		})
+	);
+}
+
 export async function focusAndExpectToHaveFocus(loc: Locator) {
 	(loc.element() as HTMLElement).focus();
 	await expect.element(loc).toHaveFocus();

tests/src/tests/combobox/combobox.browser.test.ts

@@ -306,6 +306,36 @@ describe("combobox - single", () => {
 		await expectHighlighted(item0);
 	});
 
+	it("should auto-highlight the first matching item after input when `autoHighlight` is true", async () => {
+		const t = setupSingle({ autoHighlight: true }, [
+			{ value: "1", label: "apple" },
+			{ value: "2", label: "banana" },
+			{ value: "3", label: "cherry" },
+			{ value: "4", label: "date" },
+		]);
+		await t.trigger.click({ force: true });
+		await expectExists(t.getContent());
+		const [item1, item2, item3, item4] = getItems(page.getByTestId);
+
+		await expectNotHighlighted([item1, item2, item3, item4]);
+		await t.user.type(t.input, "b");
+		await expectHighlighted(item2);
+		await expect.element(t.input).toHaveAttribute("aria-activedescendant", item2.element().id);
+		await t.user.keyboard(kbd.ESCAPE);
+		await expectNotExists(t.getContent());
+		t.unmount();
+	});
+
+	it("should clear the auto-highlight when input filtering removes all items", async () => {
+		const t = await openSingle({ autoHighlight: true });
+
+		await t.user.type(t.input, "Z");
+		await expect.element(t.input).not.toHaveAttribute("aria-activedescendant");
+		await t.user.keyboard(kbd.ESCAPE);
+		await expectNotExists(t.getContent());
+		t.unmount();
+	});
+
 	it("should navigate through the items using the keyboard (loop = true)", async () => {
 		await openSingle(
 			{

tests/src/tests/context-menu/context-menu.browser.test.ts

@@ -12,6 +12,7 @@ import {
 	getPointerAwayFromSubmenuIntentClientCoords,
 	getPointerLeaveTowardSubmenuClientCoords,
 	getPointerMidpointTowardSubmenuClientCoords,
+	pointerDown,
 } from "../browser-utils";
 import ContextMenuIntegrationTest from "./context-menu-integration-test.svelte";
 import ContextMenuNestedTest from "./context-menu-nested-test.svelte";
@@ -626,7 +627,9 @@ it("should open when right clicked inside a tooltip trigger", async () => {
 
 it("should close when the trigger is left clicked and the menu is open", async () => {
 	await open();
-	await page.getByTestId("trigger").click({ force: true });
+	const trigger = page.getByTestId("trigger");
+	await pointerDown(trigger);
+	await trigger.click({ force: true });
 	await expectNotExists(page.getByTestId("content"));
 });
 

tests/src/tests/select/select.browser.test.ts

@@ -14,7 +14,12 @@ import SelectValueChildTest from "./select-value-child-test.svelte";
 import type { SelectValueChildrenMultiTestProps } from "./select-value-children-multi-test.svelte";
 import SelectValueChildrenMultiTest from "./select-value-children-multi-test.svelte";
 import SelectViewportTest from "./select-viewport-test.svelte";
-import { expectExists, expectNotExists, observeTransitionAttrs } from "../browser-utils";
+import {
+	expectExists,
+	expectNotExists,
+	observeTransitionAttrs,
+	pointerDown,
+} from "../browser-utils";
 import SelectScrollJumpTest from "./select-scroll-jump-test.svelte";
 import { page, userEvent } from "@vitest/browser/context";
 
@@ -320,6 +325,7 @@ describe("select - single", () => {
 	it("should close on outside click", async () => {
 		const t = await openSingle();
 
+		await pointerDown(t.outside);
 		await t.outside.click({ force: true });
 		await expectNotExists(t.getContent());
 	});
@@ -783,6 +789,7 @@ describe("select - multiple", () => {
 
 	it("should close on outside click", async () => {
 		const t = await openMultiple();
+		await pointerDown(t.outside);
 		await t.outside.click({ force: true });
 		await expectNotExists(t.getContent());
 	});