Chapter 4: Releases & Versioning

Core Idea

Base UI reached stable 1.0.0 in December 2025 with 35 components; since then it has shipped monthly minor releases adding components (Drawer, OTPField), stabilizing preview APIs, and steadily improving Combobox/Autocomplete performance — install canary builds directly from pkg.pr.new when you need an unreleased fix.

Key Concepts

• Versioning scheme: single package @base-ui/react, semver, with a long alpha (Dec 2024–May 2025) → beta (May–Dec 2025) → rc → 1.0.0 (Dec 11, 2025) progression before stabilizing.
• Canary releases: published for every master commit and PR — install via npm i https://pkg.pr.new/@base-ui/react@<commit-hash> or @<PR-number>; may contain breaking changes, check the linked PR for details.
• Full changelog: authoritative history lives at github.com/mui/base-ui/blob/master/CHANGELOG.md — this skill summarizes milestones only.

Notable Milestones

• v1.0.0-alpha.4 (Dec 2024) — first public cut: 25 components, unstyled, composable open API.
• v1.0.0-alpha.7 (Mar 2025) — useRender hook introduced (now the library's core polymorphic-rendering primitive, ch050).
• v1.0.0-beta.0 (May 2025) — Menubar, NavigationMenu, ContextMenu added.
• v1.0.0-beta.3 (Sep 2025) — Combobox + Autocomplete introduced.
• v1.0.0-rc.0 (Dec 2025) — several breaking changes just before stable: Checkbox/Switch unchecked-state now matches native semantics, Tabs.Panel keepMounted behavior fixed, Combobox's keepHighlight prop removed.
• v1.0.0 (Dec 11, 2025) — stable release, 35 components, new @base-ui/react package name, new website.
• v1.1.0 (Jan 2026) — CSPProvider added (ch048); loopFocus support for Autocomplete/Combobox.
• v1.2.0 (Feb 2026) — Drawer added (preview); useFilteredItems hook for Autocomplete/Combobox.
• v1.3.0 (Mar 2026) — Drawer stabilized; Menu content transitions via Viewport; new Label parts for Select/Combobox/Slider.
• v1.4.0 (Apr 2026) — OTPField added (preview); Toast can update an existing notification by ID.
• v1.5.0 (May 2026) — closed-popup mount performance up to 50% faster, unmount up to 85% faster; sanitizeValue renamed to normalizeValue on OTPField.
• v1.6.0 (Jun 2026) — OTPField stabilized; Accordion keyboard nav aligned to WAI-ARIA APG; new Drawer.VirtualKeyboardProvider for mobile.
• v1.7.0 (Aug 4, 2026, latest at doc fetch time) — ScrollArea.Thumb WebKit overscroll feedback; bundle size and performance reductions across components.

Key Takeaways

1. Treat any component still labeled "preview" in its own chapter (OTPField history shows preview → stable took ~2 minor versions) as subject to breaking changes until its stabilization release.
2. Use canary pkg.pr.new installs to validate a fix before it lands in a numbered release, not for production dependencies.
3. Cross-check a specific component's current stability/behavior against its own chapter — this changelog is a historical summary, not a live status page.

Connects To

• ch048 (CSP Provider): introduced v1.1.0.
• ch022 (Drawer): preview in v1.2.0, stable in v1.3.0.
• ch032 (OTP Field): preview in v1.4.0, stable in v1.6.0.
• ch050 (useRender): introduced v1.0.0-alpha.7, RSC-compatible since v1.0.0-beta.1.