Setting the file. One moment.
Skill 01 · Migrate Radix To Base
Subchapter 1.4
display-misc.mdMarkdown25 KBView on GitHub
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, , formerly ).
@base-ui/react@base-ui-components/reactUniversal 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/>} />.className and style also accept a function of the part’s State object.Part.Props and Part.State types (e.g. Progress.Root.Props).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.
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed (see header). |
value | number | null / - | value | Same. Required in Base UI (default null). null = indeterminate in both. |
max | number / - | max | Same. Base UI default 100; Base UI also adds min (default 0). |
getValueLabel | (value: number, max: number) => string / - | getAriaValueText | Renamed + signature changed: Base UI is (formattedValue: string | null, value: number | null) => string. Percent math is gone; use format/locale for formatting instead. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop. Nest inside Progress.Track; width is set by the primitive. |
min (0), format (Intl.NumberFormatOptions), locale (Intl.LocalesArgument), aria-valuetext.Progress.Track (contains Indicator), Progress.Label (accessible label, <span>), Progress.Value (formatted value text, <span>, children render fn (formattedValue, value) => ReactNode).| Radix | Base UI |
|---|---|
[data-state="loading"] | [data-progressing] (boolean-presence attrs replace the enum) |
[data-state="complete"] | [data-complete] |
[data-state="indeterminate"] | [data-indeterminate] |
[data-value], [data-max] | Dropped. Read value in a className/style state function or set your own attribute. |
All Base attrs are present on Root, Track, Indicator, Label, and Value alike. State type: { status: 'indeterminate' | 'progressing' | 'complete' }.
None on either side.
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).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
type | "auto" | "always" | "scroll" | "hover" / "hover" | Dropped | Visibility is CSS-driven: style Scrollbar opacity against [data-hovering]/[data-scrolling] (hover/scroll behavior), or always-visible CSS for "always" (+ keepMounted on Scrollbar). "auto" is the default mount behavior (scrollbar only mounts when scrollable). |
scrollHideDelay | number / 600 | Dropped | Reproduce with a CSS transition-delay on the scrollbar’s opacity transition. |
dir | "ltr" | "rtl" / - | Dropped | Base UI reads direction from the DOM (dir attribute) / its DirectionProvider utility; no per-component prop. |
nonce | string / - | Dropped | No documented CSP nonce equivalent. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Same part role (the scrollable container). Wrap children in ScrollArea.Content when horizontal scrolling matters. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
forceMount | boolean / - | keepMounted | Renamed; boolean, default false. Keeps the element in the DOM when the viewport is not scrollable. |
orientation | "horizontal" | "vertical" / "vertical" | orientation | Same, same default. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop on both sides. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop on both sides. |
overflowEdgeThreshold (number | Partial<{ xStart; xEnd; yStart; yEnd }>, default 0), threshold before the overflow edge attributes flip.ScrollArea.Content (div inside Viewport; same overflow data attributes as Root).| Radix | Base UI |
|---|---|
Scrollbar [data-state="visible" | "hidden"] | Dropped. Use [data-hovering], [data-scrolling], and [data-has-overflow-x/y] on Scrollbar to drive visibility styles. |
Scrollbar/Thumb [data-orientation] | Same (data-orientation on Scrollbar and Thumb). |
| - | New, on Root/Content/Viewport/Scrollbar: data-has-overflow-x, data-has-overflow-y, data-overflow-x-start/end, data-overflow-y-start/end, data-scrolling; Scrollbar also data-hovering. |
Radix’s scroll-area docs list no CSS variables (its implementation ships undocumented --radix-scroll-area-thumb-*/corner-* vars). Base UI documents:
| Base UI variable | Where |
|---|---|
--scroll-area-corner-width, --scroll-area-corner-height | Root |
--scroll-area-thumb-width, --scroll-area-thumb-height | Scrollbar |
--scroll-area-overflow-x-start/end, --scroll-area-overflow-y-start/end | Viewport (pixel distance from each edge, great for scroll fades) |
Part mapping: Separator.Root → Separator (callable single part, no .Root).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
orientation | "horizontal" | "vertical" / "horizontal" | orientation | Same, same default (Orientation type). |
decorative | boolean / - | Dropped | Base UI’s separator is always semantic (role="separator"). For a purely visual rule, render a plain <div aria-hidden="true"> or use a CSS border instead. |
None beyond the universal className/style/render. Renders a <div>.
[data-orientation] with values horizontal | vertical: identical on both sides.
None on either side.
Part mapping: Avatar.Root → Avatar.Root, Avatar.Image → Avatar.Image, Avatar.Fallback → Avatar.Fallback. Same anatomy. Base Root renders <span>, Image <img>, Fallback <span>.
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop on both sides. Base Root can also take plain children (e.g. initials) with no Image/Fallback. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
onLoadingStatusChange | (status: "idle" | "loading" | "loaded" | "error") => void / - | onLoadingStatusChange | Same name, same ImageLoadingStatus union. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
delayMs | number / - | delay | Renamed, same meaning (ms to wait before showing the fallback). |
Nothing beyond the universal trio. Part State exposes imageLoadingStatus (and transitionStatus on Image) for className/style functions.
Radix documents none. Base UI Image adds data-starting-style / data-ending-style for enter/exit transitions.
None on either side.
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:
| Radix part | Base UI part |
|---|---|
Toast.Provider | Toast.Provider (props differ heavily) |
Toast.Viewport | Toast.Portal + Toast.Viewport (Portal is new; appends to <body> by default) |
Toast.Root | Toast.Root (requires toast object; typically wraps new Toast.Content) |
Toast.Title | Toast.Title (renders <h2>) |
Toast.Description | Toast.Description (renders <p>) |
Toast.Action | Toast.Action (rendered per-toast; props can come from toast.actionProps) |
Toast.Close | Toast.Close |
| - | New: Toast.Content, Toast.Positioner + Toast.Arrow (anchored toasts), Toast.createToastManager, Toast.useToastManager |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
duration | number / 5000 | timeout | Renamed. Same default (5000, 0 disables auto-dismiss). Per-toast override moved to add({ timeout }). |
label (required) | string / "Notification" | Dropped | Base UI handles screen reader announcements internally; per-toast urgency via priority: 'low' | 'high' in add(). |
swipeDirection | "right" | "left" | "up" | "down" / "right" | Moved | Now swipeDirection on Toast.Root; accepts a single value or an array, default ['down', 'right']. |
swipeThreshold | number / 50 | Dropped | Not configurable. Opt elements out of swipe with the data-base-ui-swipe-ignore attribute. |
announcerContainer | Element | DocumentFragment / document.body | Dropped | Closest analog is Toast.Portal container for where the viewport renders. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | On both Portal and Viewport. |
hotkey | string[] / ["F8"] | Dropped | Base UI hard-wires F6 to focus the viewport landmark; not configurable. |
label | string / "Notifications ({hotkey})" | Dropped | Landmark labelling handled internally. |
Base UI only: Portal.container (HTMLElement | ShadowRoot | ref | null).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
type | "foreground" | "background" / "foreground" | priority in add() options | Moved + renamed: foreground ≈ priority: 'high' (announced urgently), background ≈ 'low' (default). Careful: Base UI’s toast.type is a different concept (a free-form styling category like 'success', surfaced as data-type). |
duration | number / - | timeout in add() options | Moved + renamed; per-toast override of Provider timeout. |
defaultOpen | boolean / true | Dropped | Open state lives in the manager. Create with add(), remove with close(id). |
open | boolean / - | Dropped | Same as above; there is no controlled-open mode. add({ id }) upserts an existing toast in place. |
onOpenChange | (open: boolean) => void / - | Dropped (workaround) | Use onClose / onRemove callbacks in the toast object (add() options). |
onEscapeKeyDown | (event: KeyboardEvent) => void / - | Dropped | Esc-to-close still works when focus is in the viewport, but is not interceptable. |
onPause / onResume | () => void / - | Dropped | Timers still pause on hover, focus, and window blur automatically, but there are no callbacks. |
onSwipeStart / onSwipeMove / onSwipeEnd / onSwipeCancel | (event: SwipeEvent) => void / - | Dropped (workaround) | Swiping is styled, not scripted: [data-swiping], [data-swipe-direction] and --toast-swipe-movement-x/y replace the event hooks. |
forceMount | boolean / - | Dropped | Roots render from the toasts array; exit animations get data-ending-style + toast.transitionStatus: 'ending' before removal (onRemove fires after). |
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).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop. Base renders <h2> (Radix rendered <div>); pass render={<div />} to keep a div. Content usually comes from toast.title. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Only prop. Base renders <p>. Content usually comes from toast.description. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
altText (required) | string / - | Dropped | No equivalent prop. When creating toasts via the manager, pass the button’s props (including handlers and aria attributes) through add({ actionProps }). |
Base UI only: nativeButton (boolean, default true, set false when render is not a button).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
Base UI only: nativeButton (as on Action).
limit (number, default 3; overflowing toasts get data-limited + inert instead of being removed), toastManager (from Toast.createToastManager() for use outside React).useToastManager() return / createToastManager()): toasts, add(options) => id, close(id?), update(id, options), promise(promise, { loading, success, error }).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).| Radix | Base UI |
|---|---|
Root [data-state="open" | "closed"] | data-starting-style / data-ending-style (CSS transition hooks) |
Root [data-swipe="start" | "move" | "cancel" | "end"] | [data-swiping] while swiping; "end" ≈ [data-ending-style][data-swipe-direction=...] |
Root [data-swipe-direction] (up/down/left/right) | Same name and values |
| - | New: Root data-expanded, data-limited, data-type; Viewport data-expanded; Content data-behind, data-expanded; Title/Description/Close/Action data-type; Positioner/Arrow data-side, data-align, data-anchor-hidden/data-uncentered |
| Radix | Base UI |
|---|---|
--radix-toast-swipe-move-x / --radix-toast-swipe-move-y | --toast-swipe-movement-x / --toast-swipe-movement-y |
--radix-toast-swipe-end-x / --radix-toast-swipe-end-y | Dropped; animate dismissal from [data-ending-style][data-swipe-direction=...] using the movement vars |
| - | New on Root: --toast-index, --toast-offset-y, --toast-height; Viewport: --toast-frontmost-height; Positioner: --anchor-width/height, --available-width/height, --transform-origin |
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:
| Radix part | Base UI part |
|---|---|
Form.Root | Form (callable, no .Root) |
Form.Field | Field.Root |
Form.Label | Field.Label |
Form.Control | Field.Control (or any Base UI input component: Input, Checkbox, Select, … work inside Field out of the box) |
Form.Message | Field.Error (validation errors); Field.Description for plain hint text |
Form.ValidityState | Field.Validity |
Form.Submit | Dropped; use a plain <button type="submit"> |
| - | New: Fieldset.Root + Fieldset.Legend, Field.Item (per-item wrapper in checkbox/radio groups) |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
onClearServerErrors | () => void / - | Dropped (workaround) | The server-error model changed: pass an errors object (keys = Field.Root name, values = message(s)) to Form; clear your own error state in onFormSubmit (Base calls preventDefault() for you) or in onValueChange per field. |
Base UI only on Form: errors (Errors), onFormSubmit ((formValues, eventDetails) => void), validationMode ('onSubmit' | 'onBlur' | 'onChange', default 'onSubmit'), actionsRef ({ validate(fieldName?) }).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
name (required) | string / - | name | Same purpose (submission identity + matching Form errors keys); optional in Base UI and takes precedence over name on Field.Control. |
serverInvalid | boolean / - | Dropped (workaround) | Either supply the message via Form errors={{ [name]: message }} (field becomes invalid and Field.Error shows it), or force state with the invalid boolean prop on 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() }).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. Auto-association with the control is preserved. |
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).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. For composite widgets, skip Control entirely: Base UI inputs (Input, Checkbox, Select, …) wire into Field.Root directly, which Radix Form could not do. |
Base UI only: defaultValue (string | number | string[]), onValueChange ((value, eventDetails) => void).
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | render | Signature changed. |
match | 'badInput' | 'patternMismatch' | 'rangeOverflow' | 'rangeUnderflow' | 'stepMismatch' | 'tooLong' | 'tooShort' | 'typeMismatch' | 'valid' | 'valueMissing' | ((value, formData) => boolean | Promise<boolean>) / - | match | Signature changed: Base UI is boolean | 'valid' | 'badInput' | 'customError' | 'patternMismatch' | 'rangeOverflow' | 'rangeUnderflow' | 'stepMismatch' | 'tooLong' | 'tooShort' | 'typeMismatch' | 'valueMissing'. The function form is gone: move custom rules to validate on Field.Root (returns error string(s)); an Error without match then displays them. 'customError' matches validate failures. |
forceMatch | boolean / false | match={true} | Renamed/absorbed: match accepting true always shows the message (the documented hook for external libraries and server errors). |
name | string / - | Dropped | Field.Error cannot target a field from outside; it must be nested in the owning Field.Root. |
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>.
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
children | (validity: ValidityState | undefined) => React.ReactNode / - | children (required) | Signature changed: (state: Field.Validity.State) => React.ReactNode where the native flags live at state.validity.* (plus state.errors, state.error, state.value, state.initialValue). |
name | string / - | Dropped | Must be nested inside Field.Root. |
| Radix prop | Type / default | Base UI equivalent | Migration note |
|---|---|---|---|
asChild | boolean / false | Dropped | No submit part; render a plain <button type="submit"> (or the styled Button component). |
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.
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).| Radix (Field/Label/Control/Message) | Base UI (all Field parts: Root, Item, Label, Control, Description, Error) |
|---|---|
[data-valid] | [data-valid] (same) |
[data-invalid] | [data-invalid] (same) |
| - | New: data-dirty, data-touched, data-filled, data-focused, data-disabled; Error also gets data-starting-style/data-ending-style. |
None on either side.
Radix utilities with no Base UI equivalent, and the recommended plain replacements:
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.
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.
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.
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.
This file