base-ui — Claude Code skill: what it does, how to install
Provides AI agents with composition rules, accessibility patterns, and component structures for unstyled @base-ui/react primitives.
MIT 238 installs ★ 23 updated 2026-10-24
npx skills add itechmeat/llm-code --skill base-ui -a claude-codeWhat base-ui does
This skill equips coding agents with reference material for unstyled React components from @base-ui/react. It details how to assemble multi-part controls, including custom inputs like OTPField, menus, tabs, and drawer overlays.
The skill covers component composition using the render prop alongside utility helpers such as mergeProps and useRender. It also includes version 1.9.0 behaviors: popup unmounting via preventUnmountOnClose(), menu search filtering with <Menu.FilterProvider>, and focus guard handling.
Because Base UI provides purely unstyled primitives, styling must be supplied by your project using CSS modules or utility classes.
What it helps with
- Build an accessible form with validation using
FormandField - Implement a searchable dropdown using
Menu.FilterProviderandMenu.Input - Manage custom exit animations on popups by holding unmount via
preventUnmountOnClose() - Wire custom attributes and handlers onto controls using
mergeProps
Example prompts for the agent
- Generate an accessible OTP input using the Base UI
OTPFieldprimitive. - Set up a filterable dropdown menu with
@base-ui/reactcomponents. - Configure a dialog overlay that delays unmounting until closing animations complete.
How to install base-ui
1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill base-ui -a claude-code2Manually: put the files in place
~/.claude/skills/base-ui/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/base-ui/
1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill base-ui -a codex2Manually: put the files in place
.agents/skills/base-ui/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill base-ui -a cursor2Manually: put the files in place
.cursor/skills/base-ui/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install itechmeat/llm-code skills/base-ui2Manually: put the files in place
.github/skills/base-ui/SKILL.md1Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill base-ui -a gemini-cli2Platform CLI
gemini skills install https://github.com/itechmeat/llm-code --path skills/base-uiManually: put the files in place
.devin/skills/base-ui/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add itechmeat/llm-code --skill base-ui -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about base-ui
How to install base-ui in Claude Code?
Run npx skills add itechmeat/llm-code --skill base-ui -a claude-code. The skill file will be placed at ~/.claude/skills/base-ui/SKILL.md.
What does the base-ui skill do?
It provides the model with component APIs, prop definitions, and composition rules for @base-ui/react. This avoids hallucinated prop names and ensures correct handling of multi-part primitives.
How does unmount control work in Base UI 1.9.0?
Call eventDetails.preventUnmountOnClose() inside onOpenChange to keep the DOM element mounted. Once custom closing animations finish, trigger actionsRef.current.unmount() to complete the cycle.
Source text
SKILL.md · MIT
--- name: base-ui description: "Base UI unstyled React components. Covers forms, menus, overlays, composition. Use when building accessible, unstyled React UI components with @base-ui/react, composing with render props, or implementing custom-styled form controls, menus, and overlays. Keywords: @base-ui/react, render props, unstyled components." metadata: version: "1.9.0" release_date: "2026-10-09" --- # 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/tabs.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 ## Release Highlights (1.9.0) - **Menu filtering (preview)**: `<Menu.FilterProvider>` wraps a `<Menu.Root>` or `<Menu.SubmenuRoot>`, `<Menu.Input>` takes the query, and `<Menu.List>` holds the items that get filtered. `<Menu.Clear>` and `<Menu.Empty>` cover reset and no-match states. Full details in references/menu.md. - **Unmount control**: automatic unmounting is decoupled from `actionsRef`. Call `eventDetails.preventUnmountOnClose()` inside `onOpenChange` to keep the popup mounted, then end the closing phase yourself with `actionsRef.current.unmount()`. Applies to Autocomplete, Combobox, Menu, Select, Dialog, Alert Dialog, Popover, Tooltip, and Preview Card. Details in references/popover.md. - `Menu.Root` accepts `onItemHighlighted(highlightedItem, eventDetails)`. The reason is `'keyboard'`, `'pointer'`, or `'none'`; pointer events may be a `MouseEvent` rather than a `PointerEvent`, and typing reports `'none'`. - `Autocomplete` and `Combobox` support `autoHighlight` with asynchronous results, accept readonly arrays for multiple values, and report the originating event to `onItemHighlighted`. - `Menu` fixes nested menus without a root trigger, submenu closing when focus returns through its guard, repeated trigger activation toggling submenus, and the focus-guard loop when the trigger is the only tabbable element. - `Drawer` preserves swipe release velocity on 120 Hz input and after a trailing stationary pointer event, `data-base-ui-swipe-ignore` gains `x` and `y` options, and a drag starting on an SVG scrolls instead of swiping. - `Accordion.Trigger` and `Collapsible.Trigger` apply the native `disabled` attribute when rendering native buttons, and `hiddenUntilFound` panels expand synchronously on `beforematch`. - `Radio Group` and `Checkbox` prefer `aria-label` over an associated label, ignored arrow keys no longer select on refocus, and `inputRef` forwarding is fixed. - `NumberField.ScrubArea` fires `onClick` once per click, and `OTPField` no longer over-fills slots during Safari IME composition. - `Field.Control` no longer warns when an uncontrolled `defaultValue` changes, `ScrollArea` drops the presentational viewport role, and `Tabs` can select tabs with function values. - The `CssVariables` and `DataAttributes` types are now exported. ## v1.7.0 - v1.8.0 highlights - `Combobox` adds a `createItems` collection API for building the option collection programmatically. - `Avatar.Image` adds a `keepMounted` prop so the image subtree stays mounted (useful for avoiding remount flashes). - `Toast` accepts functional updates derived from the current toast, and the `render` prop is honored in `Toast.Title`, `Toast.Description`, and `Toast.Action`. - `Autocomplete` and `Combobox` emit `input-press` and `cancel-open` change event details; inline `Combobox` exposes an `expanded` state. - `Combobox.Item` and `Select.Item` inherit the disabled state from their root. - `Form` focuses the first invalid field in document order; `Field` publishes neutral validity while async validation is in flight. - Mostly accessibility fixes, popup/overlay behavior fixes, and bundle-size reductions across drawers, menus, tooltips, and scroll areas. ## 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.6.0 highlights - `OTPFieldPreview` namespace is renamed to `OTPField`; update imports that referenced the preview namespace. - Broad behavioral bug fixes across Accordion, Alert Dialog, Autocomplete, Avatar, Checkbox, Dialog, Drawer, Field, Menu, Number Field, OTP Field, and other components. ## 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. - To drive the close animation from an external library, call `eventDetails.preventUnmountOnClose()` in `onOpenChange` and finish with `actionsRef.current.unmount()`; `keepMounted` on the portal decides whether the DOM node stays. ### 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)
© itechmeat · MIT · itechmeat/llm-code