Mantle Combobox Owned Behavior Migration Guide
Combobox no longer uses @ariakit/react. Mantle's own behavior hooks drive it, the same useListbox hook that drives Select, and they follow the WAI-ARIA editable combobox with list autocomplete pattern. The parts, the keyboard, and autoSelect stay the same. These things change:
- The parts no longer take every Ariakit prop. Each part takes the props of its element, plus the props on the Combobox page.
Combobox.Rootuses mantle's selection names:value,defaultValue, andonValueChangefor the picked value;inputValue,defaultInputValue, andonInputValueChangefor the text; andopen,defaultOpen, andonOpenChange. Ariakit'svalue,defaultValue, andsetValueset the text, sovalueanddefaultValuenow mean something else.Combobox.Rootalso takesname,form, andrequired, so the picked value submits with its form.Combobox.Contentportals into the nearest overlay's positioner, or intodocument.body, asSelect.Contentdoes. It opens below the input, or above it when the space below is too small.- The highlighted item carries
data-highlightedin place ofdata-active-item. The open list carriesdata-state="open"in place ofdata-open. Combobox.ItemValuetakes noasChild.
Combobox costs 16.1 KB gzip in place of 53.4 KB (React external).
TL;DR: On Combobox.Root, rename the text props value, defaultValue, and setValue to inputValue, defaultInputValue, and onInputValueChange. Then rename selectedValue, defaultSelectedValue, and setSelectedValue to value, defaultValue, and onValueChange, and setOpen to onOpenChange. Delete Ariakit popover props from Combobox.Content and focusOnHover from Combobox.Item. Replace data-active-item with data-highlighted in class strings, CSS, and tests. Then run the type checker: it names each Ariakit prop that a part no longer takes.
Codemod
From a mantle checkout:
In a project that installs @ngrok/mantle:
The rules apply steps 2 to 4. They rename the text, selection, and open props on Combobox.Root, and delete the popover props from Combobox.Content and focusOnHover from Combobox.Item, for a Combobox import from @ngrok/mantle/combobox under its own name or an alias. A function that binds Combobox to a parameter or a local shadows the import, so the rules leave that function alone. Steps 5 to 7 stay manual: an Ariakit store or prop has no one-to-one replacement, and a data attribute in a class string, CSS, or a test is a string, not syntax. A value or defaultValue on a root with no other Ariakit prop is ambiguous, so the codemod reports it and leaves it: rename it to inputValue or defaultInputValue when it set the text. The codemod is safe to run more than once. Pass --dry-run to print the rewrites first, and run your formatter after the rewrite.
You are an agent migrating a codebase. Do this:
- Find every part of
@ngrok/mantle'sCombobox(Combobox.Root,Input,Content,Item,ItemValue,Group,GroupLabel). Search for the names, and for a renamed import (import { Combobox as MantleCombobox }). - On
Combobox.Root, rename the text props first:valuetoinputValue,defaultValuetodefaultInputValue, andsetValueorsetInputValuetoonInputValueChange. Then renameselectedValuetovalue,defaultSelectedValuetodefaultValue,setSelectedValuetoonValueChange, andsetOpentoonOpenChange. KeepopenanddefaultOpen. - On
Combobox.Content, deleteunmountOnHide,gutter,shift,placement,portal,fitViewport,flip,overflowPadding, andupdatePosition. KeepsameWidth,asChild, andclassName. - On
Combobox.Item, deletefocusOnHover. An item always takes the highlight on hover. - Run the type checker. For each Ariakit prop it names, delete the prop:
store,activeId,focusLoop,virtualFocus, orresetValueOnHideonCombobox.Root. AuseComboboxStorefrom Ariakit has no replacement: controlinputValue,value, andopeninstead.autoComplete,showOnClick,showOnChange,showOnKeyPress,setValueOnChange, orblurActiveItemOnClickonCombobox.Input. The input always uses list autocomplete and opens on a click, a keystroke, or ArrowDown.hideOnClick,setValueOnClick, orselectValueOnClickonCombobox.Item. A click always writes the item's value into the input, picks it, and closes the list. To run code on a pick, useonValueChangeonCombobox.Root.asChildonCombobox.ItemValue. Wrap it in your own element instead.
- Search class strings, CSS, and tests for
data-active-itemand replace it withdata-highlighted(for example,data-active-item:bg-…becomesdata-highlighted:bg-…). Replace adata-openread on the list withdata-state="open". - In tests, find code that read
document.activeElementas the highlighted item. DOM focus stays on the input: readaria-activedescendanton the input, ordata-highlightedon the item. - After editing, run the project's formatter, linter, type checker, and tests.
Why own the behavior? Ariakit's combobox and Radix Select each shipped their own selection state, focus, dismissal, and positioning, so a page with both paid for two copies. One
useListboxhook now holds that behavior forSelectandCombobox, so the second component costs only its own parts.
Before → after
The root props
The highlight style
Edge cases & gotchas
- While the list is open, Enter picks the highlighted item or does nothing. It never submits the form, as before. With
autoSelect={false}, submit inonKeyDownwhen the input has noaria-activedescendant, as the free-text example does. - Inside a
Dialog, the first Escape closes the list and the second closes the dialog, as before. MultiSelectmoves to the same hooks in the same release. The MultiSelect migration covers it.
How to verify
Run rg "data-active-item" in the app. It must find nothing that styles or queries a Combobox. Run the type checker, which names each Ariakit prop that a part no longer takes. Type in each combobox: the first match takes the highlight, the arrow keys move it, and Enter writes it into the input.