base-ui

What this skill does

# Base UI (React)

Base UI provides unstyled, composable React components. This skill focuses on assembling multi-part components, composing with the `render` prop, and meeting accessibility requirements while you supply styling.

## Quick navigation (references)

### Utilities

- references/csp-provider.md
- references/direction-provider.md
- references/merge-props.md
- references/use-render.md

### Forms & inputs

- references/form.md
- references/fieldset.md
- references/input.md
- references/number-field.md
- references/otp-field.md
- references/radio.md
- references/select.md
- references/slider.md
- references/switch.md

### Feedback & status

- references/meter.md
- references/progress.md
- references/toast.md

### Menus, navigation, overlays

- references/drawer.md
- references/menu.md
- references/menubar.md
- references/navigation-menu.md
- references/popover.md
- references/preview-card.md
- references/tooltip.md

### Toggles & controls

- references/toggle.md
- references/toggle-group.md
- references/toolbar.md

### Layout & separators

- references/scroll-area.md
- references/separator.md

## v1.4.1 highlights

- `mergeProps` now forwards multi-argument event handlers correctly, which matters for wrapped callbacks that receive extra details/state alongside the event.
- Tabbability with `display: contents` was fixed; retest custom wrappers and render-prop compositions that flatten DOM structure.
- Popup sizing on rapid trigger hover was fixed, and clipped-item highlight clearing inside scroll containers is more reliable.

## v1.5.0 highlights

- `OTPField` replaces `sanitizeValue()` with `normalizeValue()` and improves keyboard shortcut plus validation-composition behavior.
- Popup-based components now respect controlled `open` state more consistently, which affects `Popover`, `Menu`, `PreviewCard`, and related overlays.
- `Form`, `Field`, and `OTPField` avoid older `flushSync`-style validation timing patterns; retest any local validation scheduling workarounds before keeping them.
- RTL behavior is corrected across `NavigationMenu`, `Popover`, and `ScrollArea`.
- `Drawer.Viewport` now forwards `style`, which is useful for custom viewport sizing and animated layout constraints.

## v1.4.0 highlights

- `OTPField` arrives as a preview primitive for one-time-password and verification-code entry.
- Hidden inputs expose `form` and `suppressHydrationWarning`, which matters when controls submit to external forms or hydrate across SSR boundaries.
- `render` warnings and `preventBaseUIHandler()` runtime behavior are more reliable in composed components.
- Overlay/input primitives received important behavioral fixes across `Drawer`, `NavigationMenu`, `Select`, `Slider`, `Toast`, and `Switch`.

## v1.3.0 highlights

- Drawer is now stable (no longer preview) and should be treated as a first-class overlay primitive.
- Autocomplete and Combobox add `InputGroup`; Combobox, Select, and Slider add `Label` parts.
- Drawer adds `SwipeArea` for explicit swipe affordances.
- Tooltip adds `closeOnClick`; Toast can close all toasts.
- Checkbox, Radio Group, and Switch improve automatic `aria-labelledby` support.
- `render` prop support from v1.2.0 remains relevant, including lazy elements.

## Core concepts to apply

- **Unstyled primitives**: all visuals come from your CSS/Tailwind/CSS Modules. Base UI handles behavior and accessibility.
- **Multi-part anatomy**: most components follow `Root` + subparts (`Trigger`, `Popup`, `Item`, etc.). Assemble them explicitly.
- **`render` prop**: replace the default element or wrap with your own component; when using the function form, merge props manually with `mergeProps`.
- **State-driven styling**: many parts expose data attributes such as `data-[popup-open]`, `data-[highlighted]`, `data-[pressed]`, `data-[checked]`, `data-[invalid]`, etc.
- **Portals for overlays**: use `Portal` + `Positioner` + `Popup` for popovers, menus, tooltips, select, navigation menu content, and preview cards.

## Recipes

### 1) Build accessible forms quickly

- Wrap inputs with `Form` for submission and error aggregation.
- Use `Field.Root` with a `name`, then `Field.Label`, `Field.Control`, and `Field.Error` for labels and errors.
- Group related fields with `Fieldset.Root` + `Fieldset.Legend`.
- For `Radio` groups, either use `RadioGroup` with `aria-labelledby`, or render `RadioGroup` via `Fieldset.Root` and use `Field.Label` for each option.
- Ensure **every** form control has an accessible name (label or `Field`/`Fieldset` labeling pattern).

### 2) Compose with `render` + `mergeProps`

- When passing a React element to `render`, Base UI merges props automatically.
- When passing a function to `render`, **merge** Base UI props and your props with `mergeProps`.
- Use `event.preventBaseUIHandler()` inside merged event handlers to stop Base UI’s internal behavior when needed (synthetic events only).

### 3) Overlays and menus (portaled UI)

- Build popups using `Root` + `Trigger` + `Portal` + `Positioner` + `Popup`.
- For menus and navigation, add `Item`, `Separator`, `Arrow`, and list/viewport parts as needed.
- `NavigationMenu.Link` supports `render` for framework router links.

### 4) Toasts

- Wrap the app (or a subtree) with `Toast.Provider`.
- Use `Toast.useToastManager()` to create toasts.
- Render a `Toast.Viewport` inside `Toast.Portal`, then map `toasts` to `Toast.Root` entries with `Toast.Content`, `Toast.Title`, `Toast.Description`, and `Toast.Close`.

### 5) RTL and CSP constraints

- For RTL behavior, wrap with `DirectionProvider` and also set `dir="rtl"` (provider does not set the DOM direction).
- For strict CSP, wrap with `CSPProvider` and pass `nonce`, or disable inline style elements if your app supplies external styles. Beware inline style **attributes** are not controlled by `CSPProvider`.

### 6) Sliders and ranges

- Single value sliders: one `Slider.Thumb`.
- Range sliders: pass an array and render a `Slider.Thumb` per value; add `index` for SSR alignment.
- Adjust thumb alignment with `thumbAlignment` when edge alignment is required.

## Critical prohibitions

- Do not omit accessible labels for inputs, sliders, switches, or radio groups.
- Do not expect Base UI to provide default styling; apply your own styles.
- Do not forget `Portal` for overlays that need to escape stacking/overflow contexts.
- Do not skip `mergeProps` when using the function form of `render`.

## Output expectations

When responding to the user, provide:

- The specific Base UI components to use (and their key parts).
- A brief assembly plan (Root + parts + portal/positioner where relevant).
- A short checklist for accessibility and state-driven styling.

## Links

- [Documentation](https://base-ui.com/)
- [Releases](https://github.com/mui/base-ui/releases)
- [GitHub](https://github.com/mui/base-ui)
- [npm](https://www.npmjs.com/package/@base-ui-components/react)