Migrate Radix To Base

Radix UI -> Base UI migration

You migrate shadcn wrappers, hand-rolled radix compositions, and their consumers to @base-ui/react, keeping the project buildable at every step. Be precise; never guess a mapping. When a prop or part is not in these reference files, check node_modules/@base-ui/react/**/*.d.ts before transforming, and record gaps in the report.

Preflight (always)

1. npx shadcn@latest info --json (or the project's runner): gives the current base, STYLE (e.g. radix-lyra), tailwind version, aliases, installed components, and package manager. Trust it over inference. 2. Detect the package manager (packageManager field / lockfile: pnpm-lock.yaml, bun.lock, yarn.lock, package-lock.json) and use IT for every install. Never leave a stale lockfile. 3. Require a clean git tree; work on a branch; one commit per component. 4. Baseline check BEFORE touching dependencies: run the project's typecheck/build so pre-existing failures are never attributed to you. 5. Install @base-ui/react alongside radix. Radix packages are removed only after the LAST component is migrated (both coexist fine).

Strategy: golden pair first, transformation engine second

• Golden pair via the CLI (preferred). If the project is shadcn with a

known style (radix-<style>), the shadcn CLI itself is the golden-pair executor: 1. Classify each ui wrapper FIRST: diff the user's file against its stock origin, using the components.json style VERBATIM in the URL (https://ui.shadcn.com/r/styles/<style>/<component>.json, files[0].content). This works for prefixed styles (radix-nova) AND legacy unprefixed ones (new-york, new-york-v4, default), which are all still served. 2. WHOLE-PROJECT mode: flip components.json style radix-<style> -> base-<style> now. PROGRESSIVE mode: do NOT flip yet (the project is still mostly radix; the flip happens once, after the last component); fetch base variants directly by URL instead (https://ui.shadcn.com/r/styles/base-<style>/<component>.json). 3. PRISTINE wrappers, whole-project mode: shadcn add <component> --overwrite delivers the base variant with the project's exact icon/font/preset resolution. Never bulk --all --overwrite; go component by component, or you drown in unrelated registry version drift. PROGRESSIVE mode: never use --overwrite (it destroys the original that consumers still import); write the fetched base variant content to <component>-base.tsx instead. 4. CUSTOMIZED wrappers: fetch the base variant and replay the user's diff onto it (their customizations must SURVIVE; --overwrite would destroy them). Mechanical implementation that works at scale: git merge-file user.tsx radix-golden.tsx base-golden.tsx (three-way merge, radix golden as ancestor) auto-resolves most files; hand-resolve conflicts with the reference tables. 5. MANDATORY leftover sweep on EVERY golden-pair file, including ones that merged "clean": grep -n "radix-ui\|@radix-ui\|IconPlaceholder" per file. The registry sometimes reorders functions between variants, which makes three-way merges report zero conflicts while leaving stale radix hunks in place. A clean merge is NOT proof of a clean file. This is more reliable than reconstructing transforms; use it whenever the pair exists. Consumer/app code has no CLI mechanism: always hand-migrate it against consumer-props.md.

• **Legacy styles (new-york, new-york-v4, default): classification only, no

replay.** These have no base counterpart (there is no base-new-york), and retargeting onto a base-<style> variant would restyle the user's app. Use the radix golden ONLY to detect customizations, then run the transformation engine on the user's OWN file: rewire primitives, keep their exact classes, apply class-mapping renames. Their look stays theirs. At the end of a legacy whole-project migration, FLAG (do not fix): the style name still reads as radix to the CLI, so future shadcn add will deliver radix variants; the user decides whether to switch style or add manually.

• Transformation engine (fallback). Hand-rolled radix code, non-shadcn

projects, unknown styles: transform using universal-patterns.md (imports in BOTH forms: radix-ui and @radix-ui/react-*; asChild->render with the worked example; Portal>Positioner>Popup; the positioner FORWARD rule; part renames), the per-family props tables (overlays.md, menus.md, form-controls.md, disclosure.md, display-misc.md), class-mapping.md for data-attribute/CSS-var rewrites, and wrapper-shapes.md for exact target shapes (tooltip arrow, SubContent defaults, select anatomy).

Modes

Progressive (default). "Migrate accordion" = one component, strangler-fig: 1. Detect in-progress state first: an existing <component>-base.tsx, consumers split between old/new imports. The files ARE the state; resume, never restart. 2. If the component imports other ui wrappers still on radix (select -> button), STOP and recommend migrating those first, bottom-up. 3. Write the migrated version to <component>-base.tsx (original untouched; golden-pair content fetched by URL, or transformed by hand, per the strategy above); typecheck. Repoint consumers ONE AT A TIME (imports + the call-site props in consumer-props.md); typecheck each. When no consumer imports the original: delete it, rename -base -> original, flip imports back, final check, commit. When the LAST radix wrapper in the project is finalized, flip components.json to base-<style> and remove radix deps.

Whole project (only when explicitly asked): same per-component work in dependency order (leaf/shared wrappers like button and label first). After wrappers, sweep ALL app code against consumer-props.md — the call-site break surface is much larger than asChild. Then remove radix deps, install, full build.

Hard rules

• NEVER touch non-radix libraries or their wrappers: cmdk (command), vaul

(drawer), sonner, input-otp, react-day-picker (calendar), recharts (chart). Report them as intentionally untouched.

• No Base UI counterpart: AspectRatio -> CSS aspect-ratio div; Label ->

native <label>; VisuallyHidden -> sr-only; Direction -> Direction Provider (direction prop, not dir). Popover Anchor and NavigationMenu Indicator have no equivalent: inert passthrough + flag.

• button.tsx migrates to the REAL @base-ui/react/button primitive, never

a hand-rolled useRender wrapper.

• Behavior deltas are FLAGGED, never silently patched (tabs manual

activation, menu items not closing on click, nav-menu 50ms delay). The target is idiomatic Base UI matching the shadcn base registry.

• Honest reporting: skipped/reverted files are listed as flagged, never as

migrated. Pre-existing failures are named as pre-existing.

Verify and report

Typecheck per file, build per batch, full build at the end vs the baseline.

Reports live in a .migration/ directory at the project root, ONE FILE PER COMPONENT: .migration/<component>.md (e.g. .migration/accordion.md). Rules:

• Each run writes (or fully overwrites) the file for each component it

migrated. Re-running a component replaces its report; never touch other components' files.

• A multi-component run ("migrate alert-dialog and dropdown-menu") writes one

file per component, each self-contained; shared consumer-sweep notes are repeated in every affected file.

• Whole-project mode writes the per-component files plus

.migration/project.md (dependency swap, app-code sweep summary, final build result).

• There is NO index file. Migration status is derived from disk, not

maintained: scan the project's ui directory (the ui alias from shadcn info, e.g. components/ui or src/components/ui) for remaining radix imports when asked "what's left". End every run's summary with that derived count ("N wrappers remain on Radix").

Each .migration/<component>.md uses EXACTLY this structure (it is documented publicly; reports must match it):

# <component>

<date, strategy used (golden pair via CLI / merge / engine), one-line verdict>

## Changed

<every file touched, with what changed and why; include file:line for
anything notable. Confirm the leftover scan is clean:
grep -n "radix-ui\|@radix-ui" on this component's files>

## Left alone

<files that look related but were intentionally not touched, with the reason
(cmdk/vaul/sonner are not radix; unrelated drift; etc.)>

## Behavior changes

<differences that compile fine but act differently; flagged, never patched
(tabs activation, menu close-on-click, delays...). Empty section if none>

## Verify by hand

<short manual QA checklist for this primitive family: focus return on
dialogs, keyboard nav + typeahead on menus/select, tooltip delay feel,
slider commit events. Concrete steps, one minute of clicking>

Class-string rewrites (layer 2)

Apply these across ALL class strings (className, cva definitions, cn calls), including app code. They are safe, mechanical rewrites.

Data-attribute selectors

Animation idiom

Radix (tw-animate/keyframes): data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=closed]:animate-out data-[state=closed]:fade-out-0

Base UI (transition + starting/ending styles): transition-[opacity,transform] data-starting-style:opacity-0 data-ending-style:opacity-0 (plus translate/scale equivalents).

Do not translate animate-in/out utilities 1:1; restate the intent with data-starting-style: / data-ending-style: transitions. When the original uses per-side slide classes, keep the data-[side=...] or data-[swipe-direction=...] parameterization.

CSS variables

Element changes kill pseudo-class variants

When a part's rendered element changes from a form control to a generic element (checkbox/switch/radio Roots render <span> in Base UI), disabled: and :disabled Tailwind variants become dead code. Replace them with data-disabled: equivalents. (Note: the shadcn base registry's checkbox still carries the dead disabled:* classes; treat that as an upstream quirk, not a pattern to copy.)

Disabled-state hooks

Some Base UI triggers surface disabled state as aria-disabled rather than the disabled attribute (accordion trigger, tabs tab). Where the radix code used disabled:opacity-50, add or substitute aria-disabled:opacity-50 according to the wrapper's reference file.

Consumer-side prop changes (call sites, not wrappers)

The shadcn wrapper NAMES survive a radix -> base-ui migration, but these props change or disappear at CALL SITES in app code. Sweep every consumer for this list after migrating the wrappers. All entries verified against @base-ui/react@1.6.0 type definitions during real migrations; when in doubt, check node_modules/@base-ui/react/*/.d.ts, never guess.

Universal

Per component

Callback signature rule

Base UI callbacks commonly gain an event-details argument: onOpenChange(open, eventDetails), onValueChange(value, eventDetails). Passing an existing single-arg handler stays type-safe; handlers that USED Radix's event parameter need review against the family reference file.

Sweep procedure

1. grep app code (outside components/ui) for each LHS token above plus asChild. 2. Fix call sites file by file; typecheck after each file. 3. Anything on this list marked FLAG goes into the migration report as a behavior delta, never silently patched.

Radix → Base UI props mapping: disclosure + toggle family

Scope: accordion, collapsible, tabs, toggle, toggle-group, toolbar. Sources: radix-ui.com primitives docs + base-ui.com .md docs, cross-checked against installed @base-ui/react@1.6.0 .d.ts files (the published docs page for accordion lagged; types are authoritative here).

Conventions that apply to every component below:

• asChild (boolean, default false) → render (ReactElement | (props: HTMLProps, state) => ReactElement). Signature changed: instead of a lone child element, pass the element to render; Base UI merges props onto it. Button-rendering parts additionally accept nativeButton (default true), set it to false when render produces a non-<button> element.
• Base UI className and style also accept a (state) => value function form.
• Radix data-[state=...] value attributes become Base UI presence attributes (data-open, data-closed, data-pressed, data-active).
• Base UI change callbacks all gained a second eventDetails argument ({ reason, event, cancel(), ... }).
• Radix dir props are dropped everywhere; Base UI reads direction from the DOM dir attribute / DirectionProvider.

---

accordion

Part mapping: Root → Root, Item → Item, Header → Header, Trigger → Trigger, Content → Panel.

Accordion.Root → Accordion.Root

Accordion.Item → Accordion.Item

Accordion.Header → Accordion.Header

Accordion.Trigger → Accordion.Trigger

Accordion.Content → Accordion.Panel

Base UI only props worth knowing

• Root.hiddenUntilFound / Panel.hiddenUntilFound (default false): uses hidden="until-found" so browser find-in-page can expand panels; overrides keepMounted. No Radix equivalent.
• Root.keepMounted: root-level version of the per-panel prop.
• Item.onOpenChange: (open: boolean, eventDetails: Accordion.Item.ChangeEventDetails) => void, per-item open callback. No Radix equivalent.
• Trigger.nativeButton (default true).
• className / style state-function forms on every part.

Data-attribute mapping

CSS var mapping

---

collapsible

Part mapping: Root → Root, Trigger → Trigger, Content → Panel.

Collapsible.Root → Collapsible.Root

Collapsible.Trigger → Collapsible.Trigger

Collapsible.Content → Collapsible.Panel

Base UI only props worth knowing

• Panel.hiddenUntilFound (default false): find-in-page support via hidden="until-found"; overrides keepMounted.
• Trigger.nativeButton (default true).
• className / style state-function forms.

Data-attribute mapping

CSS var mapping

---

tabs

Part mapping: Root → Root, List → List, Trigger → Tab, Content → Panel. Base UI adds an Indicator part with no Radix equivalent.

Tabs.Root → Tabs.Root

Tabs.List → Tabs.List

Tabs.Trigger → Tabs.Tab

Tabs.Content → Tabs.Panel

Base UI only props worth knowing

• Tabs.Indicator: new part, a <span> that tracks the active tab for sliding-highlight UIs; renderBeforeHydration (default false) for SSR-flash avoidance. Exposes the --active-tab-* CSS vars below.
• List.activateOnFocus (see above).
• Tab.nativeButton, state-function className/style on all parts.

Data-attribute mapping

CSS var mapping

Radix Tabs exposes no CSS variables. Base UI only (on Indicator): --active-tab-left, --active-tab-right, --active-tab-top, --active-tab-bottom, --active-tab-width, --active-tab-height.

---

toggle

Part mapping: Toggle.Root → Toggle (single-part; Base UI export is directly callable, no .Root).

Toggle.Root → Toggle

Base UI only props worth knowing

• value?: string: identifies the toggle inside a Base UI ToggleGroup (this replaces Radix ToggleGroup.Item's value, see toggle-group below).
• nativeButton (default true), state-function className/style.

Data-attribute mapping

CSS var mapping

None on either side.

---

toggle-group

Part mapping: ToggleGroup.Root → ToggleGroup (callable single export), ToggleGroup.Item → Toggle (Base UI reuses the Toggle primitive as group items).

ToggleGroup.Root → ToggleGroup

ToggleGroup.Item → Toggle

Note: the item also gains the full standalone Toggle API (pressed, defaultPressed, onPressedChange with eventDetails) since it IS the Toggle primitive; inside a group the group value normally drives pressed state.

Base UI only props worth knowing

• multiple (covered above) and the always-array value model.
• Items are plain Toggles, so per-item onPressedChange is available.
• State-function className/style.

Data-attribute mapping

CSS var mapping

None on either side.

---

toolbar

Part mapping: Root → Root, Button → Button, Link → Link, Separator → Separator. Toolbar.ToggleGroup/Toolbar.ToggleItem are DROPPED as dedicated parts: compose the standalone ToggleGroup with <Toolbar.Button render={<Toggle />} value="..."> as items (Base UI docs pattern). Base UI adds Group and Input parts with no Radix equivalent.

Toolbar.Root → Toolbar.Root

Toolbar.Button → Toolbar.Button

Toolbar.Link → Toolbar.Link

Toolbar.ToggleGroup → ToggleGroup (standalone, composed)

Toolbar.ToggleItem → Toolbar.Button render={<Toggle />}

Toolbar.Separator → Toolbar.Separator

Base UI only props worth knowing

• Root.disabled: disables the entire toolbar (no Radix equivalent).
• Toolbar.Group (new part): groups related items, with a group-level disabled (default false).
• Toolbar.Input (new part): <input> wired into toolbar arrow-key navigation; defaultValue, disabled (default false), focusableWhenDisabled (default true).
• Button.disabled (default false) + Button.focusableWhenDisabled (default true): disabled buttons remain focusable for discoverability; set focusableWhenDisabled={false} for Radix-like behavior.
• Button.nativeButton (default true), state-function className/style on all parts.

Data-attribute mapping

CSS var mapping

None on either side.

Radix UI → Base UI props mapping: progress, scroll-area, separator, avatar, toast, form

Sources: radix-ui/website data/primitives/docs/components/*.mdx (full inline prop tables) and base-ui.com /react/components/{progress,scroll-area,separator,avatar,toast,form,field,fieldset}.md (fetched 2026-07-02, @base-ui/react, formerly @base-ui-components/react).

Universal conventions (apply to every part below, not repeated per table):

• asChild (boolean) → render (ReactElement | ((props: HTMLProps, state) => ReactElement)). Signature changed: <Part asChild><a/></Part> → <Part render={<a/>} />.
• Base UI className and style also accept a function of the part's State object.
• Every Base part exposes Part.Props and Part.State types (e.g. Progress.Root.Props).

---

progress

Part mapping: Progress.Root → Progress.Root, Progress.Indicator → Progress.Indicator (now MUST be nested in the new Progress.Track). Base UI adds Track, Label, Value parts. The primitive computes the Indicator fill width itself (inline style), so the Radix pattern style={{ transform: translateX(-(100 - value)%) }} on Indicator is deleted, not ported.

Progress.Root → Progress.Root

Progress.Indicator → Progress.Indicator

Base UI only props worth knowing

• Root: min (0), format (Intl.NumberFormatOptions), locale (Intl.LocalesArgument), aria-valuetext.
• New parts: Progress.Track (contains Indicator), Progress.Label (accessible label, <span>), Progress.Value (formatted value text, <span>, children render fn (formattedValue, value) => ReactNode).

Data attributes

All Base attrs are present on Root, Track, Indicator, Label, and Value alike. State type: { status: 'indeterminate' | 'progressing' | 'complete' }.

CSS variables

None on either side.

---

scroll-area

Part mapping: ScrollArea.Root → ScrollArea.Root, ScrollArea.Viewport → ScrollArea.Viewport, ScrollAreaScrollbar → ScrollArea.Scrollbar, ScrollAreaThumb → ScrollArea.Thumb, ScrollArea.Corner → ScrollArea.Corner. Base UI adds ScrollArea.Content (wraps content inside Viewport, needed for horizontal overflow measurement).

ScrollArea.Root → ScrollArea.Root

ScrollArea.Viewport → ScrollArea.Viewport

ScrollAreaScrollbar → ScrollArea.Scrollbar

ScrollAreaThumb → ScrollArea.Thumb

ScrollArea.Corner → ScrollArea.Corner

Base UI only props worth knowing

• Root: overflowEdgeThreshold (number | Partial<{ xStart; xEnd; yStart; yEnd }>, default 0), threshold before the overflow edge attributes flip.
• New part: ScrollArea.Content (div inside Viewport; same overflow data attributes as Root).

Data attributes

CSS variables

Radix's scroll-area docs list no CSS variables (its implementation ships undocumented --radix-scroll-area-thumb-*/corner-* vars). Base UI documents:

---

separator

Part mapping: Separator.Root → Separator (callable single part, no .Root).

Separator.Root → Separator

Base UI only props worth knowing

None beyond the universal className/style/render. Renders a <div>.

Data attributes

[data-orientation] with values horizontal | vertical: identical on both sides.

CSS variables

None on either side.

---

avatar

Part mapping: Avatar.Root → Avatar.Root, Avatar.Image → Avatar.Image, Avatar.Fallback → Avatar.Fallback. Same anatomy. Base Root renders <span>, Image <img>, Fallback <span>.

Avatar.Root → Avatar.Root

Avatar.Image → Avatar.Image

Avatar.Fallback → Avatar.Fallback

Base UI only props worth knowing

Nothing beyond the universal trio. Part State exposes imageLoadingStatus (and transitionStatus on Image) for className/style functions.

Data attributes

Radix documents none. Base UI Image adds data-starting-style / data-ending-style for enter/exit transitions.

CSS variables

None on either side.

---

toast

The mental model changes completely: Radix toast is declarative (you render <Toast.Root open> yourself), Base UI toast is manager-driven. Toasts are created imperatively via Toast.useToastManager().add({ title, description, ... }) (or a global Toast.createToastManager() passed to Provider toastManager), and you render useToastManager().toasts.map((toast) => <Toast.Root key={toast.id} toast={toast} />) inside the Viewport.

Part mapping:

Toast.Provider → Toast.Provider

Toast.Viewport → Toast.Portal + Toast.Viewport

Base UI only: Portal.container (HTMLElement | ShadowRoot | ref | null).

Toast.Root → Toast.Root

Base UI only on Root: toast (required Toast.Root.ToastObject: id, title, description, type, timeout, priority, updateKey, limited, height, onClose, onRemove, actionProps, positionerProps, data), swipeDirection (single or array).

Toast.Title → Toast.Title

Toast.Description → Toast.Description

Toast.Action → Toast.Action

Base UI only: nativeButton (boolean, default true, set false when render is not a button).

Toast.Close → Toast.Close

Base UI only: nativeButton (as on Action).

Base UI only props worth knowing

• Provider: limit (number, default 3; overflowing toasts get data-limited + inert instead of being removed), toastManager (from Toast.createToastManager() for use outside React).
• Manager API (useToastManager() return / createToastManager()): toasts, add(options) => id, close(id?), update(id, options), promise(promise, { loading, success, error }).
• New parts: Toast.Content (clips overflow while the stack is collapsed; data-behind, data-expanded), Toast.Positioner/Toast.Arrow for anchored toasts (full popup positioning surface: anchor, side default 'top', align, sideOffset, alignOffset, collisionAvoidance, collisionBoundary, collisionPadding, arrowPadding, sticky, positionMethod, disableAnchorTracking).

Data attributes

CSS variables

---

form

Base UI splits Radix Form across three components: Form (@base-ui/react/form, a callable single part rendering <form>), Field (@base-ui/react/field: Root, Label, Control, Error, Description, Validity, Item), and Fieldset (@base-ui/react/fieldset: Root, Legend).

Part mapping:

Form.Root → Form

Base UI only on Form: errors (Errors), onFormSubmit ((formValues, eventDetails) => void), validationMode ('onSubmit' | 'onBlur' | 'onChange', default 'onSubmit'), actionsRef ({ validate(fieldName?) }).

Form.Field → Field.Root

Base UI only on Field.Root: validate ((value, formValues) => string | string[] | Promise<...> | null, the custom-validation replacement for Radix function match), validationMode, validationDebounceTime (0), disabled, invalid, dirty, touched, actionsRef ({ validate() }).

Form.Label → Field.Label

Base UI only: nativeLabel (boolean, default true; set false when render swaps in a non-label element, e.g. a <div> labelling a <Select.Trigger> button).

Form.Control → Field.Control

Base UI only: defaultValue (string | number | string[]), onValueChange ((value, eventDetails) => void).

Form.Message → Field.Error

Note: Radix rendered default English messages per match when children were omitted; Base UI renders the error string coming from validate/Form errors, otherwise provide children. Field.Description (className/style/render only) is the new home for non-error helper text. Error renders a <div>, Description a <p>.

Form.ValidityState → Field.Validity

Form.Submit → (none)

(new) Fieldset.Root and Fieldset.Legend

No Radix counterpart. Fieldset.Root renders a native <fieldset> (props: className/style/render; state { disabled }, data-disabled). Fieldset.Legend renders a <div> automatically associated as the accessible legend. Use to group related fields under one label.

Base UI only props worth knowing (form-wide)

• Validation timing is configurable (validationMode on Form or per Field, validationDebounceTime).
• actionsRef imperative validate() on both Form and Field.Root.
• Field.Item groups a single checkbox/radio inside a group with its own label/description (disabled prop).
• Focus is moved to the first invalid field on submit, matching Radix behavior.

Data attributes

CSS variables

None on either side.

---

No Base UI counterpart

Radix utilities with no Base UI equivalent, and the recommended plain replacements:

Label (radix Label.Root: asChild, htmlFor)

Use a native <label htmlFor="...">, or Field.Label when inside a Field.Root (which auto-wires the association, no htmlFor needed). Radix's only behavioral extra (preventing text selection on double click) is one line of CSS: select-none / user-select: none.

AspectRatio (radix AspectRatio.Root: asChild, ratio default 1)

Use the CSS aspect-ratio property, which is what the prop mapped to: ratio={16 / 9} → aspect-video or aspect-[16/9] (aspect-ratio: 16 / 9), plus w-full and object-cover on the media child.

VisuallyHidden (radix VisuallyHidden.Root: asChild)

Use Tailwind's sr-only class on a <span> (the standard clip-rect pattern). Note: some Base UI popup components in other files still need hidden titles for a11y; <span className="sr-only"> covers that too.

AccessibleIcon (radix AccessibleIcon.Root: label required)

It was only VisuallyHidden + aria-hidden composed: render the icon with aria-hidden="true" (or focusable="false") and add <span className="sr-only">{label}</span> next to it, or put aria-label={label} on the interactive parent (button/link) instead.

Radix UI to Base UI props mapping: form controls

Scope: select, checkbox, radio-group, switch, slider. Sources: radix-ui.com primitives docs and base-ui.com /react/components/*.md (fetched 2026-07-02).

Global conventions that apply to every part below:

• asChild (Radix, boolean, default false) -> render (Base UI, ReactElement | ((props, state) => ReactElement)). Every Base UI part accepts render, plus className/style as either plain values or state callbacks ((state) => ...).
• Base UI parts that render interactive elements accept nativeButton (tells Base UI whether the render target is a native <button>), which has no Radix equivalent.
• Callbacks fire with a second eventDetails argument ({ reason, event, cancel(), allowPropagation(), isCanceled, isPropagationAllowed, trigger }). eventDetails.cancel() replaces Radix's event.preventDefault() pattern for preventing default component behavior.
• Radix data-state="x" tokens become presence attributes in Base UI (data-checked, data-unchecked, data-open, ...). Base UI adds Field-integration attributes everywhere (data-valid, data-invalid, data-dirty, data-touched, data-filled, data-focused) and animation attributes (data-starting-style, data-ending-style).
• Radix dir props have no Base UI per-component equivalent, direction comes from DirectionProvider (or the dir HTML attribute).

---

select

Part mapping: Root -> Root, Trigger -> Trigger, Value -> Value, Icon -> Icon, Portal -> Portal, Content -> Portal > Positioner > Popup (split into three parts), Viewport -> List, Item -> Item, ItemText -> ItemText, ItemIndicator -> ItemIndicator, ScrollUpButton -> ScrollUpArrow, ScrollDownButton -> ScrollDownArrow, Group -> Group, Label -> GroupLabel (Base UI's Select.Label is a NEW part that labels the trigger, not groups), Separator -> Separator, Arrow -> Arrow.

Select.Root → Select.Root

Base UI Select.Root renders no HTML element (Radix Root doesn't either).

Select.Trigger → Select.Trigger

Select.Value → Select.Value

Select.Icon → Select.Icon

Select.Portal → Select.Portal

Select.Content → Select.Portal > Select.Positioner > Select.Popup (moved/split)

Radix Content handled positioning, collision, and the panel in one part. In Base UI, positioning props live on Positioner, panel/focus props live on Popup, dismiss interception lives on Root.onOpenChange eventDetails.

Select.Viewport → Select.List (renamed)

Select.Item → Select.Item

Select.ItemText → Select.ItemText

Select.ItemIndicator → Select.ItemIndicator

Select.ScrollUpButton / ScrollDownButton → Select.ScrollUpArrow / ScrollDownArrow (renamed)

Select.Group → Select.Group

Select.Label → Select.GroupLabel (renamed)

Select.Separator → Select.Separator

Select.Arrow → Select.Arrow

Base UI only props worth knowing (select)

• Root.multiple: boolean (default false): multi-select with Value[] values, no Radix equivalent.
• Root.items: Record<string, ReactNode> | { label, value }[] | Group[], lets Select.Value render labels instead of raw values.
• Root.isItemEqualToValue, Root.itemToStringLabel, Root.itemToStringValue: object-value support.
• Root.modal: boolean (default true): scroll lock + outside pointer blocking; Radix select was always modal-ish, set modal={false} for non-modal behavior.
• Root.readOnly, Root.autoComplete, Root.form, Root.inputRef, Root.id, Root.onOpenChangeComplete, Root.actionsRef ({ unmount() } for externally controlled exit animations), Root.highlightItemOnHover (default true).
• New parts: Select.Backdrop (overlay under the popup), Select.Label (trigger label), Popup.finalFocus.
• Positioner.anchor, Positioner.positionMethod ('absolute' | 'fixed'), Positioner.disableAnchorTracking.

Data-attribute mapping (select)

CSS variable mapping (select)

All Base UI vars are set on Select.Positioner (Radix set them on Content, popper mode only):

---

checkbox

Part mapping: Root -> Root, Indicator -> Indicator. Element change: Radix Root renders a <button> plus hidden input inside a form; Base UI Root renders a <span> plus hidden <input> always (use nativeButton + render to render a real button).

Checkbox.Root → Checkbox.Root

Checkbox.Indicator → Checkbox.Indicator

Base UI only props worth knowing (checkbox)

• Root.indeterminate: boolean (default false): the mixed state, decoupled from checked.
• Root.parent: boolean + CheckboxGroup (new component, base-ui.com/react/components/checkbox-group): <CheckboxGroup value/defaultValue/onValueChange(string[], eventDetails)/allValues/disabled> provides shared state for a set of checkboxes and enables a parent "select all" checkbox. No Radix equivalent, new capability.
• Root.readOnly: boolean, Root.uncheckedValue: string (value submitted when unchecked), Root.form: string, Root.inputRef, Root.id, Root.nativeButton.

Data-attribute mapping (checkbox)

No CSS variables on either side.

---

radio-group

Part mapping: Radix ships one RadioGroup namespace; Base UI splits it into RadioGroup (a single component, no sub-parts) and Radio (Radio.Root, Radio.Indicator). RadioGroup.Root -> RadioGroup, RadioGroup.Item -> Radio.Root, RadioGroup.Indicator -> Radio.Indicator. Element change: Radix Item renders <button>; Base UI Radio.Root renders <span> plus hidden <input> (use nativeButton + render for a real button).

RadioGroup.Root → RadioGroup

RadioGroup.Item → Radio.Root (moved to Radio namespace)

RadioGroup.Indicator → Radio.Indicator (moved to Radio namespace)

Base UI only props worth knowing (radio-group)

• RadioGroup.readOnly, RadioGroup.form, RadioGroup.inputRef (the group owns one hidden input).
• Radio.Root.readOnly, Radio.Root.inputRef, Radio.Root.nativeButton.

Data-attribute mapping (radio-group)

No CSS variables on either side.

---

switch

Part mapping: Root -> Root, Thumb -> Thumb. Element change: Radix Root renders <button> + hidden input in forms; Base UI Root renders <span> plus hidden <input> always (use nativeButton + render for a real button).

Switch.Root → Switch.Root

Switch.Thumb → Switch.Thumb

Base UI only props worth knowing (switch)

• Root.readOnly: boolean, Root.uncheckedValue: string, Root.form: string, Root.inputRef, Root.id, Root.nativeButton (default false).

Data-attribute mapping (switch)

No CSS variables on either side.

---

slider

Part mapping: Root -> Root, Track -> Track, Range -> Indicator (renamed), Thumb -> Thumb, plus a NEW required Control part: Base UI anatomy is Root > Control > Track > (Indicator, Thumb). Control is the clickable/draggable surface (Radix Root handled pointer interaction itself). Base UI also adds Value and Label parts. Element change: Radix Thumb renders a plain element wrapped by an invisible span with a hidden input in forms; Base UI Thumb renders a <div> with a nested <input type="range">.

Slider.Root → Slider.Root

Slider.Track → Slider.Track (moved inside Control)

Slider.Range → Slider.Indicator (renamed)

Slider.Thumb → Slider.Thumb

(new part) Slider.Control

No Radix equivalent. The interactive surface that receives pointer events; wrap Track with it. Props: className/style/render only.

Base UI only props worth knowing (slider)

• Root.thumbAlignment: 'center' | 'edge' | 'edge-client-only' (default 'center'): whether the thumb center or edge aligns with the control edge at min/max. Radix always behaved like 'edge'-ish via CSS; Base UI defaults to 'center', set thumbAlignment="edge" to keep the thumb inside the track bounds.
• Root.thumbCollisionBehavior: 'push' | 'swap' | 'none' (default 'push'): range-slider thumb collision handling (Radix behavior was closest to 'none').
• Root.largeStep: number (default 10): Page Up/Down and Shift+Arrow increment.
• Root.format: Intl.NumberFormatOptions and Root.locale: Intl.LocalesArgument: value formatting for Slider.Value and aria-valuetext.
• New parts: Slider.Value (renders <output>, children: (formattedValues: string[], values: number[]) => ReactNode), Slider.Label (auto-associated label).

Data-attribute mapping (slider)

No CSS variables on either side (Radix slider positions thumbs via inline styles; Base UI does the same).

Radix → Base UI props mapping: menu family

Sources: radix-ui.com primitives docs (dropdown-menu, context-menu, menubar, navigation-menu) and base-ui.com /react/components/{menu,context-menu,menubar,navigation-menu}.md, fetched 2026-07-02.

Part-mapping ground truth (from our wrappers): Content → Portal > Positioner > Popup (side/sideOffset/align/alignOffset live on Positioner); Label → GroupLabel; ItemIndicator → CheckboxItemIndicator/RadioItemIndicator; Sub → SubmenuRoot; SubTrigger → SubmenuTrigger; navigation-menu Viewport → Positioner > Popup > Viewport, Indicator → Icon; asChild → render.

Cross-cutting rules (apply to every part below):

---

dropdown-menu (Radix DropdownMenu → Base UI Menu)

Root → Menu.Root

Trigger → Menu.Trigger

Portal → Menu.Portal

Content → Menu.Portal > Menu.Positioner > Menu.Popup

Arrow → Menu.Arrow

Item → Menu.Item

Group → Menu.Group

Label → Menu.GroupLabel

CheckboxItem → Menu.CheckboxItem

RadioGroup → Menu.RadioGroup

RadioItem → Menu.RadioItem

ItemIndicator → Menu.CheckboxItemIndicator / Menu.RadioItemIndicator

Separator → Menu.Separator

Sub → Menu.SubmenuRoot

SubTrigger → Menu.SubmenuTrigger

SubContent → Menu.Portal > Menu.Positioner > Menu.Popup (inside SubmenuRoot)

Same prop fates as Content above; Radix-specific defaults to be aware of: align default is "start" on SubContent (Base Positioner default is 'center' — set align="start" explicitly if you relied on the Radix default; in practice submenu popups anchor to the trigger item and our wrappers set this). Radix SubContent has no side prop (side is implied); Base Positioner accepts side (use 'inline-end' for RTL-aware submenus). All outside/escape callbacks, forceMount, loop, collision props map identically to Content.

Base UI only props worth knowing (Menu)

• Root: highlightItemOnHover (true), actionsRef ({ unmount(), close() }), onOpenChangeComplete(open) (fires after close animation; replaces the Radix "wait for animation" dance), closeParentOnEsc (false), disabled, orientation ('vertical'), detached-trigger machinery: handle (Menu.Handle via Menu.createHandle()), triggerId/defaultTriggerId, payload-aware children render function.
• Trigger: openOnHover, delay (100), closeDelay (0), payload, handle, nativeButton (true).
• Backdrop: new part, overlay under the popup.
• Positioner: anchor, positionMethod ('absolute'), disableAnchorTracking, sticky (boolean, viewport-keeping).
• Popup: finalFocus.
• Viewport: new part for animating content swaps with multiple/detached triggers.
• LinkItem: new part, <a>-rendering menu item (closeOnClick default false).
• All parts: className/style accept state-callback form (state) => ....

Data-attribute mapping (dropdown/context/menubar menus)

CSS variable mapping (per menu flavor: dropdown-menu / context-menu / menubar)

Base UI Menu.Viewport additionally exposes --popup-width / --popup-height (previous-content dimensions during transitions).

---

context-menu (Radix ContextMenu → Base UI ContextMenu)

Base UI ContextMenu shares the Menu part set: Root, Trigger, Portal, Backdrop, Positioner, Popup, Arrow, Item, Group, GroupLabel, Separator, SubmenuRoot, SubmenuTrigger, RadioGroup, RadioItem, RadioItemIndicator, CheckboxItem, CheckboxItemIndicator, LinkItem. Everything not listed below maps exactly as in the dropdown-menu section.

Root → ContextMenu.Root

Trigger → ContextMenu.Trigger

Portal → ContextMenu.Portal

Identical mapping to Menu.Portal (forceMount → keepMounted, container widened).

Content → ContextMenu.Portal > Positioner > Popup

Same fates as dropdown-menu Content for: asChild, loop (→ Root loopFocus), onCloseAutoFocus (→ Popup finalFocus), onEscapeKeyDown/onPointerDownOutside/onFocusOutside/onInteractOutside (→ Root onOpenChange reasons), forceMount (→ Portal keepMounted), avoidCollisions (→ collisionAvoidance), collisionBoundary (default [] → 'clipping-ancestors'), collisionPadding (0 → 5), sticky (dropped, see menu note), hideWhenDetached (→ CSS on data-anchor-hidden).

Radix-specific deltas:

Arrow / Item / Group / Label / CheckboxItem / RadioGroup / RadioItem / ItemIndicator / Separator / Sub / SubTrigger / SubContent

Identical fates to the dropdown-menu section (Label → GroupLabel, ItemIndicator → CheckboxItemIndicator/RadioItemIndicator, Sub → SubmenuRoot, SubTrigger → SubmenuTrigger, SubContent → Portal > Positioner > Popup). Menubar/ContextMenu submenus in Base are the same components with the same props (onOpenChange eventDetails, label, onClick/closeOnClick, keepMounted).

Base UI only, data attributes, CSS variables

Same as the Menu lists above; ContextMenu.Root additionally supports handle (MenuHandle<unknown>), triggerId/defaultTriggerId, actionsRef, onOpenChangeComplete, highlightItemOnHover, closeParentOnEsc, disabled, orientation. Trigger data attributes: data-popup-open, data-pressed (replacing Radix Trigger [data-state]). CSS vars: --radix-context-menu-* → --transform-origin/--available-*/--anchor-* on Positioner.

---

menubar (Radix Menubar → Base UI Menubar + Menu)

Base UI's menubar module exports a single <Menubar> container. Every menu inside it is built from Menu.* parts (Menu.Root, Menu.Trigger, Menu.Portal, Menu.Positioner, Menu.Popup, items, submenus...). So the Radix Menubar.Menu/Trigger/Portal/Content/... parts all map to the Menu component family from the dropdown-menu section.

Root → Menubar

Base UI only on Menubar: modal (boolean, true), disabled (boolean, false), orientation ('horizontal' \| 'vertical', 'horizontal').

Menu → Menu.Root

Note: Menu.Root inside a Menubar accepts all Menu.Root props (open, defaultOpen, onOpenChange(open, eventDetails), modal, loopFocus, orientation, disabled, ...). Hover-switching between menubar menus is built in.

Trigger → Menu.Trigger

Portal / Content / Arrow / Item / Group / Label / CheckboxItem / RadioGroup / RadioItem / ItemIndicator / Separator / Sub / SubTrigger / SubContent

All identical to the dropdown-menu section (they are literally the same Base UI Menu components):

• Portal.forceMount → keepMounted; container widened.
• Content (loop, onCloseAutoFocus, outside/escape callbacks, forceMount, side/sideOffset/align/alignOffset, avoidCollisions, collisionBoundary, collisionPadding, arrowPadding, sticky, hideWhenDetached) → Menu.Portal > Menu.Positioner > Menu.Popup with the exact fates listed for dropdown-menu Content.
• SubContent align default "start" note applies as in dropdown-menu.
• Items: onSelect → onClick + closeOnClick, textValue → label.
• Radix Menubar CheckboxItem/RadioItem [data-state="checked" \| "unchecked"] → data-checked/data-unchecked.

Data attributes / CSS variables

• Menubar container: Radix Root had none; Base Menubar exposes data-orientation ('horizontal' \| 'vertical'), data-has-submenu-open, data-modal.
• Menu-part attributes and --radix-menubar-* CSS vars map exactly as in the dropdown-menu tables (--transform-origin, --available-width/height, --anchor-width/height on Menu.Positioner).

---

navigation-menu (Radix NavigationMenu → Base UI NavigationMenu)

Base UI parts: Root, List, Item, Trigger, Icon, Content, Portal, Backdrop, Positioner, Popup, Arrow, Viewport, Link. Popup positioning is real anchored positioning (like Menu): the shared popup renders as Portal > Positioner > Popup > Viewport, and each Item's Content is moved into the Viewport when active. Radix's "Viewport rendered below the list" model is replaced by this anchored Positioner model (our wrappers removed the viewport boolean prop accordingly).

Root → NavigationMenu.Root

Base UI only on Root: closeDelay (50), actionsRef ({ unmount() }), onOpenChangeComplete(open). Root renders a <nav> element (Radix Root also rendered <nav>; Base renders <div> when nested).

Sub → nested NavigationMenu.Root

List → NavigationMenu.List

Item → NavigationMenu.Item

Trigger → NavigationMenu.Trigger

Content → NavigationMenu.Content

Link → NavigationMenu.Link

Indicator → NavigationMenu.Icon (per wrapper ground truth)

Viewport → NavigationMenu.Portal > Positioner > Popup > Viewport

Base UI only props worth knowing (NavigationMenu)

• Root: closeDelay, actionsRef, onOpenChangeComplete.
• New parts: Backdrop, Arrow, Positioner (real collision-aware positioning — Radix nav-menu had none), Icon.
• Content.keepMounted for crawler-visible SSR content.
• Link.closeOnClick.
• All parts accept className/style state-callback forms and render.

Data-attribute mapping (navigation-menu)

CSS variable mapping (navigation-menu)

---

Gaps / caveats

• Radix prop descriptions are rendered in JS popovers; types/defaults above were extracted from the pages' embedded type payloads ((open: boolean) => void, (checked: boolean) => void, (value: string) => void, (event: KeyboardEvent) => void, (event: PointerDownOutsideEvent) => void, (event: FocusOutsideEvent) => void, (event: PointerDownOutsideEvent | FocusOutsideEvent) => void, (event: Event) => void for onSelect/onCloseAutoFocus, Boundary = Element | null | Array<Element | null>, sticky: "partial" | "always", dir: "ltr" | "rtl") — all verified against the fetched HTML.
• Base UI ContextMenu.Root genuinely lacks modal; Menubar lacks the value/onValueChange system; ContextMenu.Trigger lacks disabled. These are the three hard drops with no one-line workaround.
• Base UI docs fetched from the .md endpoints reflect Base UI 1.x (repo currently pins 1.6.0).

Target wrapper shapes (golden-derived specifics)

Facts learned by diffing hand migrations against the shadcn base registry wrappers. These close gaps the mapping tables cannot express: exact classes, defaults, and composition shapes. When migrating shadcn-style wrappers, prefer these shapes.

Conventions

• Positioner parts get NO data-slot attribute; keep data-slot on the parts

the radix wrapper already had.

• Menu-family Positioner: className="isolate z-50 outline-none"; the Popup

KEEPS z-50 and outline-none too. Tooltip: Popup keeps z-50, Positioner gets isolate z-50. Select: isolate z-50 lives on the Popup, Positioner gets no class.

• The base registry adds cn-<comp>-content-logical (and for tooltip also

cn-tooltip-arrow-logical) companion classes next to the existing cn-<comp>-content hooks on popover, tooltip, hover-card, dropdown, context-menu, select, menubar popups. Add them when the source uses cn-* hooks; skip for plain-Tailwind projects.

Button

Base UI HAS a Button primitive: import { Button as ButtonPrimitive } from "@base-ui/react/button". A shadcn button.tsx with the Slot/asChild idiom migrates to <ButtonPrimitive> directly (which supports render), NOT to a hand-rolled useRender wrapper. Reserve useRender + mergeProps for non-button polymorphic components (breadcrumb link, marker).

Tooltip Arrow (literal classes)

<TooltipPrimitive.Arrow
  className={cn(
    "cn-tooltip-arrow cn-tooltip-arrow-logical",
    "data-[side=bottom]:top-1 data-[side=left]:right-[-13px] data-[side=left]:top-1/2! data-[side=left]:-translate-y-1/2 data-[side=right]:left-[-13px] data-[side=right]:top-1/2! data-[side=right]:-translate-y-1/2 data-[side=top]:-bottom-2.5",
    className
  )}
/>

Verify against the current base registry tooltip before relying on the exact pixel values; the shape (per-side offsets + translate, no rotation) is the stable part. Golden default: alignOffset = 0, sideOffset = 4.

DropdownMenu / ContextMenu SubContent

Compose the PUBLIC Content wrapper, do not rebuild from primitives:

function DropdownMenuSubContent(props) {
  return (
    <DropdownMenuContent
      align="start"
      alignOffset={-3}
      side="right"
      sideOffset={0}
      className={cn("w-auto", props.className)}
      {...props}
    />
  )
}

The -3 / 0 defaults are load-bearing (visual alignment with the parent menu). NOTE: the live registry shapes SubContent differently per menu: context-menu is a true minimal compose (as above), while dropdown-menu's SubContent duplicates the full content class list (including translucent menu styling) rather than composing. When a golden pair exists, copy the golden shape; this example is the fallback.

DANGER — do not confuse SubContent defaults with main-Content defaults. The values above are ONLY for the submenu wrappers (DropdownMenuSubContent / ContextMenuSubContent). The MAIN ContextMenuContent (the pointer-anchored right-click menu) keeps its own positioning — do NOT apply side="right"/alignOffset to it, or every right-click menu mispositions.

• ContextMenu SUBContent defaults: align="start" alignOffset={4} side="right" sideOffset={0}.
• DropdownMenu SUBContent defaults: align="start" alignOffset={-3} side="right" sideOffset={0}.
• Main Content (either): keep the wrapper's existing align/sideOffset; do not add a side.

SubTrigger open styling

Base wrappers ADD data-popup-open:bg-accent data-popup-open:text-accent-foreground to SubTrigger (no radix equivalent class existed; the open styling was previously data-[state=open]).

Select

• Bare re-export: const Select = SelectPrimitive.Root (no wrapper function,

no data-slot on Root). SelectPrimitive.Root.Props is GENERIC (<Value, Multiple>), which breaks the usual ComponentProps pattern; the bare re-export sidesteps it.

• Drop the radix position prop entirely; expose alignItemWithTrigger

(default true) picked from Positioner.Props, sideOffset = 4.

• Item anatomy: ItemText FIRST with `cn-select-item-text shrink-0

whitespace-nowrap, then ItemIndicator render={<span className="cn-select-item-indicator" />}`.

• Scroll arrows get top-0 w-full / bottom-0 w-full; List has no classes.

Accordion animation placement

h-(--accordion-panel-height), data-starting-style:h-0, and data-ending-style:h-0 all go on the INNER div of the Panel (the element that previously carried the radix height animation), not on the Panel itself.

Tabs

The base registry accepts Base UI's manual-activation default (no activateOnFocus), and does not forward orientation beyond what the radix wrapper did. Match it: flag the behavior delta, do not patch it.