UUI 2.0 — New major version in development

Summary

Announcing the development of a new major version of the Umbraco UI component library.
We have begun work on version 2.0 of the Umbraco UI library. The primary motivator for publishing a new major version of the UI library is to accommodate the changing styleguides for Umbraco-related products. This release also includes breaking changes to package structure, import paths, and runtime requirements.

The headline change is the refresh of the UI facade of components and changes to colors, borders, and more.

See this pull request for an explanation and visual changes: #1237

The biggest change to the code is an internal one: The consolidation of ~84 individual @umbraco-ui/uui-* npm packages into a single @umbraco-ui/uui package. This simplifies installation, versioning, and dependency management for all consumers.

For the most common use case — installing @umbraco-ui/uui and importing it through a bundler — the upgrade is straightforward: npm install @umbraco-ui/uui@latest and import '@umbraco-ui/uui' continue to work as before. The breaking changes mainly affect consumers who imported individual @umbraco-ui/uui-* sub-packages, used removed components, or referenced the old CSS paths.

Developers working on V1 will be able to upgrade easily — For the most part, you are probably using the UI library's components in your HTML. There will be no change to this - all components are still present and have the same names, except for the two deprecated components listed below.

Timeline

👉 The first UUI 2.0 prerelease is scheduled for March 2026
👉 The final release is expected in June 2026, aligning with Umbraco v18.

Changes

Umbraco CMS (users and developers)

No changes to usage within the Umbraco CMS. All component names remain the same, and all import paths remain. You will notice the refreshed visuals, and that's it.

For developers, you will import from:

import { UUIButtonelement } from '@umbraco-cms/backoffice/external/uui'

Other consumers

If you already import the library through the UUI package, you only need to update the main stylesheet:

// ✔ this remains in place
import '@umbraco-ui/uui';

- <link rel="stylesheet" href="node_modules/@umbraco-ui/uui-css/dist/uui-css.css" />
+ <link rel="stylesheet" href="node_modules/@umbraco-ui/uui/themes/light.css" />

Breaking changes in UUI 2.0 for developers:

• Single package — @umbraco-ui/uui is now the actual library (no longer a meta-package that re-exports 84 sub-packages); import '@umbraco-ui/uui' still registers all components
• New import paths — individual component imports change from @umbraco-ui/uui-button to @umbraco-ui/uui/components/button/button.js
• Lit 3 — upgraded from Lit ^2.8.0 to Lit ^3.0.0
• ESM-only — the package is now "type": "module" (no CommonJS)
• Removed deprecated components — uui-popover and uui-caret have been removed
• Theme stylesheet renamed — uui-css.css is now themes/light.css; new themes/dark.css added
• Dropped polyfills — element-internals-polyfill and requestSubmit polyfill are no longer bundled (baseline browser support)

Other changes for developers

• 90+% reduction in SonarQube issues — Moving files around often allows addressing other generic issues in one sweep, and this is no different. We have squashed more than 90% of all SonarQube issues.
• 1000% improvement in build time — Perhaps a minor thing for most, but for developers contributing to the UI library, this is a major factor where the build time went from 20 to 1-2 seconds locally, allowing for swift development.
• Code simplification — Many TODOs and deprecations have been addressed, slimming the overall code base even further.
• 100% Trusted Publishing — Starting in v1.16, three core packages (uui, uui-css, uui-base) were already published via npm Trusted Publishing. The other 81 packages used granular npm tokens with --provenance, which produces provenance attestations but still authenticates through a stored secret. With a single package in v2, every release is fully covered by Trusted Publishing — no tokens anywhere in the publish pipeline.

Migration documentation and codemod tooling will be provided to help consumers update their code.

Trusted Publishing

Starting with UUI 2.0, every release of @umbraco-ui/uui is published to npm via npm Trusted Publishing — an OIDC-based mechanism where the npm registry authenticates directly with GitHub Actions, with no tokens or secrets involved.

This means every published version is cryptographically tied to a specific commit in this repository and a specific CI workflow run. npm records this as a provenance attestation, and you can see it on the package page:

The provenance record shows:

• Source Commit — the exact commit the package was built from
• Build File — the specific workflow file (.github/workflows/publish.yml) that ran
• Public Ledger — a Sigstore transparency log entry, independently verifiable

You can verify any installed version yourself:

npm audit signatures

Why this matters

Starting in v1.16, three core packages (uui, uui-css, uui-base) were moved to Trusted Publishing. The other 81 packages continued to be published using granular npm tokens with --provenance, which produces provenance attestations but still authenticates through a stored secret rather than direct CI identity.

With a single package in v2, every release is fully covered — no tokens anywhere in the publish pipeline. The trust chain runs directly from source commit → GitHub Actions → npm registry.

Previous behavior

• 84 separate npm packages (@umbraco-ui/uui-button, @umbraco-ui/uui-input, @umbraco-ui/uui-base, etc.), each independently versioned and published
• @umbraco-ui/uui existed as a meta-package that depended on all 84 individual packages — import '@umbraco-ui/uui'; registered every component at once
• Per-component import: import '@umbraco-ui/uui-button';
• Deep imports: import { UUIButtonElement } from '@umbraco-ui/uui-button';
• Foundation utilities: import { LabelMixin } from '@umbraco-ui/uui-base';
• CSS/styles: import { UUITextStyles } from '@umbraco-ui/uui-css';
• Theme stylesheet: @umbraco-ui/uui-css/dist/uui-css.css
• Lit ^2.8.0
• Both CommonJS and ESM are supported
• uui-popover and uui-caret components available (deprecated but functional)
• element-internals-polyfill and requestSubmit polyfill bundled

New behavior

• Single package — @umbraco-ui/uui is now the actual library (no longer a meta-package that re-exports 84 sub-packages); import '@umbraco-ui/uui' still registers all components
• Installation: npm install @umbraco-ui/uui
• Usage: import '@umbraco-ui/uui'; (registers all components) or import '@umbraco-ui/uui/components/button/button.js'; (cherry-pick)
• Deep imports: import { UUIButtonElement } from '@umbraco-ui/uui' (re-exported from root) or import { UUIButtonElement } from '@umbraco-ui/uui/components/button/button.js'; for bundling with tree-shaking
• Foundation utilities: import { LabelMixin } from '@umbraco-ui/uui';
• CSS/styles: import { UUITextStyles } from '@umbraco-ui/uui';
• Theme stylesheet: import '@umbraco-ui/uui/themes/light.css' (renamed from uui-css.css)
• NEW dark theme: import '@umbraco-ui/uui/themes/dark.css';
• Lit ^3.0.0 required
• ESM-only ("type": "module")
• uui-popover removed — use uui-popover-container (native Popover API)
• uui-caret removed — use uui-symbol-expand
• Polyfills dropped — modern baseline browser support assumed

Type of breaking change

Source incompatible — all import paths change, two components removed, Lit major version bump.

Reason for change

• Simplified dependency management — one install instead of 84, no more version mismatches between UUI packages
• Better tree-shaking — individual ES module entry points allow bundlers to include only the components you use
• Reduced maintenance overhead — single build, single version, single release process
• Modern web standards — Lit 3, native Popover API, baseline browser support without polyfills

Recommended action

1. Update your dependencies

If you already use @umbraco-ui/uui as a bundle import, just update:

npm install @umbraco-ui/uui@latest

If you installed individual sub-packages, remove them and switch to the single package:

npm uninstall @umbraco-ui/uui-button @umbraco-ui/uui-input @umbraco-ui/uui-base ...
npm install @umbraco-ui/uui@latest

2. Update import paths

v1 pattern	v2 pattern
@umbraco-ui/uui-{name}	@umbraco-ui/uui/components/{name}/{name}.js
@umbraco-ui/uui-{name}/lib/{file}	@umbraco-ui/uui/components/{name}/{file}.js
@umbraco-ui/uui-base	@umbraco-ui/uui
@umbraco-ui/uui-base/lib/{subpath}	@umbraco-ui/uui
@umbraco-ui/uui-css/lib/{file}	@umbraco-ui/uui

3. Update theme/CSS references

- <link rel="stylesheet" href="node_modules/@umbraco-ui/uui-css/dist/uui-css.css" />
+ <link rel="stylesheet" href="node_modules/@umbraco-ui/uui/themes/light.css" />

4. Replace removed components

- <uui-caret></uui-caret>
+ <uui-symbol-expand></uui-symbol-expand>

- <uui-popover ...>
+ <uui-popover-container ...>

5. Upgrade Lit to v3

If your project uses Lit 2, follow the Lit 2 to 3 upgrade guide.

6. CDN / bundler-free usage

UUI 2.0 can still be loaded directly from a CDN (e.g., jsdelivr), but you now need a browser import map to resolve lit and @umbraco-ui/uui imports. See docs/USAGE-WITHOUT-BUNDLER.md for a full example.

Full migration guide: docs/MIGRATION-V1-TO-V2.md

Codemod tooling to automate import path updates is planned.

Affected APIs

• All @umbraco-ui/uui-* package imports (84 packages)
• @umbraco-ui/uui-base → re-exported from @umbraco-ui/uui
• @umbraco-ui/uui-css → re-exported from @umbraco-ui/uui; stylesheet uui-css.css → themes/light.css
• Removed: uui-popover (→ uui-popover-container), uui-caret (→ uui-symbol-expand)
• Lit peer dependency: ^2.8.0 → ^3.0.0

Support

When version 2.0 launches in June 2026, we intend to transition version 1.x into its security phase, which means we will continue to support it in terms of security fixes. However, we do not expect any bug fixes or feature updates to be available. Read more in our security policy.