[combobox] Add keywords matching

[markocupic024]

Solves #3998

Screen.Recording.2026-02-07.at.00.13.10.mov

[pkg-pr-new]

• base-ui-tanstack-start

• vite-css-base-ui-example

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/react@4007
  

  pnpm add https://pkg.pr.new/mui/base-ui/@base-ui/utils@4007
  

commit: 14bde3c

[mui-bot]

Bundle size report

Bundle	Parsed size	Gzip size
@base-ui/react	🔺+436B(+0.10%)	🔺+173B(+0.13%)

Details of bundle changes

---

Check out the code infra dashboard for more information about this PR.

[netlify]

✅ Deploy Preview for base-ui ready!

Name	Link
🔨 Latest commit	14bde3c
🔍 Latest deploy log	https://app.netlify.com/projects/base-ui/deploys/69867ed4f8d5ab0008053193
😎 Deploy Preview	https://deploy-preview-4007--base-ui.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds keyword matching support to the combobox component, allowing items to be matched against additional search terms beyond their label/value. When an item object includes a keywords array property, those keywords (trimmed of whitespace) are matched alongside the item's label during filtering.

• Added resolveItemKeywords utility to extract and normalize keywords from item objects
• Enhanced both createCollatorItemFilter and createSingleSelectionCollatorFilter to check keywords before falling back to label matching
• Exposed filter prop in public ComboboxRoot API with updated documentation
• Added comprehensive test coverage demonstrating email address matching via keywords
• Updated documentation in both MDX and JSON API reference files

The implementation is clean, follows existing patterns, and integrates seamlessly with the existing Intl.Collator-based filtering system.

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The implementation is well-structured, thoroughly tested, and properly documented. The keyword matching logic is defensive (handles null/undefined, type checks, trimming), integrates cleanly with existing filter infrastructure, and maintains backward compatibility. No breaking changes or risky patterns detected.
• No files require special attention

Important Files Changed

Filename	Overview
packages/react/src/utils/resolveValueLabel.tsx	Added resolveItemKeywords function to extract and trim keywords from item objects
packages/react/src/combobox/root/utils/index.ts	Added matchesKeywords helper and integrated keyword matching into filter functions
packages/react/src/combobox/root/ComboboxRoot.tsx	Added filter prop to public API with documentation about keyword matching behavior
packages/react/src/combobox/root/ComboboxRoot.test.tsx	Added test case verifying keyword matching with email addresses, including trimming behavior

[colmtuite]

Are you working at Operate?

Is the goal with this UI for it to be a simple search widget, where the items are links? Or are the items supposed be selectable? If the UI is a search widget, then this is not a Combobox, and you should be using Autocomplete with fuzzy matching https://base-ui.com/react/components/autocomplete#fuzzy-matching

[markocupic024]

Are you working at Operate?

Is the goal with this UI for it to be a simple search widget, where the items are links? Or are the items supposed be selectable? If the UI is a search widget, then this is not a Combobox, and you should be using Autocomplete with fuzzy matching https://base-ui.com/react/components/autocomplete#fuzzy-matching

I do not know what is Operate.

This is the Comobox component which already exists and is not new UI, there is a linked issue with an explanation