Mantle MultiSelect Owned Behavior Migration Guide
MultiSelect no longer uses @ariakit/react, and mantle no longer depends on Ariakit. The useListbox hook that drives Select and Combobox now drives MultiSelect too. The parts, the tags, lockedValues, the keyboard, and the hidden form inputs 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 MultiSelect page.
MultiSelect.Rootuses mantle's selection names:value,defaultValue, andonValueChangefor the picked values;inputValue,defaultInputValue, andonInputValueChangefor the text; andopen,defaultOpen, andonOpenChange. Ariakit'svalue,defaultValue, andsetValueset the text, sovalueanddefaultValuenow mean something else.MultiSelect.InputdropsonValueChange: useonInputValueChangeonMultiSelect.Root.- The list is always modal, as Ariakit made it by default.
MultiSelect.Contentdropsmodal,backdrop,preventBodyScroll,portalElement,unmountOnHide, and the other Ariakit popover props. It portals into the nearest overlay's positioner, or intodocument.body, asSelect.Contentdoes. - The highlighted item carries
data-highlightedin place ofdata-active-item. - A closed list renders no items. The items mount when the list opens.
MultiSelect costs 18.9 KB gzip in place of 57.2 KB (React external). In a heap measurement of 300 mounted instances, each one holds about half the memory it held before, and mounts in less than half the time.
TL;DR: On MultiSelect.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 the Ariakit popover props from MultiSelect.Content and focusOnHover from MultiSelect.Item. Replace data-active-item with data-highlighted. 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 MultiSelect.Root, and delete the popover props from MultiSelect.Content and focusOnHover from MultiSelect.Item, for a MultiSelect import from @ngrok/mantle/multi-select under its own name or an alias. A function that binds MultiSelect 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'sMultiSelect. Search for the name, and for a renamed import (import { MultiSelect as MantleMultiSelect }). - On
MultiSelect.Root, rename the text props first:valuetoinputValue,defaultValuetodefaultInputValue, andsetValueorsetInputValuetoonInputValueChange. Then renameselectedValuetovalue,defaultSelectedValuetodefaultValue,setSelectedValuetoonValueChange, andsetOpentoonOpenChange. KeepopenanddefaultOpen. Move anonValueChangefromMultiSelect.InputtoonInputValueChangeonMultiSelect.Root: it gets the whole filter text, as before. - On
MultiSelect.Content, deletemodal,backdrop,preventBodyScroll,portal,portalElement,unmountOnHide,gutter,shift,placement,fitViewport,flip,overflowPadding, andupdatePosition. KeepsameWidth,asChild, andclassName. - On
MultiSelect.Item, deletefocusOnHover. An item always takes the highlight on hover. - Run the type checker. For each Ariakit prop it names, delete the prop. A
useComboboxStorefrom Ariakit has no replacement: controlinputValue,value, andopenonMultiSelect.Rootinstead.hideOnInteractOutsidehas no replacement: a press outside the trigger and the list always closes it.modal={false}has no replacement: the list is always modal. - Search class strings, CSS, and tests for
data-active-itemand replace it withdata-highlighted. Replace adata-openread on the list withdata-state="open". - In tests, find code that expected the items in the DOM while the list was closed, or that read the list inside
[data-mantle-modal-content]. Open the list first, and find the list inside the overlay's positioner ([data-slot~="dialog-positioner"],alert-dialog-positioner, orsheet-positioner). - After editing, run the project's formatter, linter, type checker, and tests.
Why own the behavior? Ariakit shipped its own store, focus, dismissal, and positioning, which
SelectandComboboxalready own in mantle's hooks. With all three pickers on oneuseListboxhook, a page pays for that behavior once, and mantle drops a dependency.
Before → after
The text and popover props
Edge cases & gotchas
- Inside a
Dialog,AlertDialog, orSheet, the first Escape closes the list and the second closes the overlay, as before. MultiSelect.Item asChildwith a bare text child now throws when the list opens, as before, because the items mount on open.
How to verify
Run rg "data-active-item" in the app. It must find nothing. Run the type checker, which names each Ariakit prop that a part no longer takes. Open each multi-select, pick and remove values with the mouse and the keyboard, and check that a press outside closes the list.