Upgrade guide

Proper UI is at v0.2.0. This page explains how versioning works, how to update, and what changed in each release that can affect existing code.

v0.2.0

The first release after two teams migrated real products onto 0.1.0 and reported what they hit. Everything is additive except the items below.

RouterProvider moved to its own subpath. It imports next/navigation, and re-exporting it from @properui/ui/providers broke Vite builds that never installed Next. Next.js projects update one import:

-import { RouterProvider, ThemeProvider } from "@properui/ui/providers";
+import { ThemeProvider } from "@properui/ui/providers";
+import { RouterProvider } from "@properui/ui/providers/router-provider";

Vite projects need no change; they use React Aria's own RouterProvider.

ModalHeader's background pattern is off unless you pass an icon. It used to default on. Pass hasBackgroundPattern explicitly if you relied on it with a bare media slot.

Label renders no * when the field is not required. It was hidden with CSS before, so a test that matched the accessible name "Email *" now matches "Email".

Select's accessible name is its label alone, not React Aria's "value, label" concatenation, and Checkbox's hint sits outside the <label>, linked with aria-describedby. Queries written against the old names need the shorter string.

DemoNativeSelect is gone. It was an internal placeholder; use NativeSelect from base/select/select-native.

Copied components: properui add now exits non-zero when npm dependencies are missing and neither --yes nor a terminal is available, printing the install command last. CI scripts that relied on exit 0 in that state should pass --yes or install first. init no longer writes a hand-rolled ThemeProvider; it copies the registry's next-themes one. Run diff to see the change if you customised the old file.

The full lists live in the @properui/ui changelog and the @properui/cli changelog.

Versioning

@properui/ui and the properui CLI are versioned and released independently, each following semantic versioning. Releases are managed with Changesets: a change lands with a changeset describing its impact (patch, minor, or major), and publishing the release regenerates the changelog from those changesets.

While the project is on 0.x, any release may include a breaking change: semver doesn't promise stability below 1.0.0. Once @properui/ui reaches 1.0.0, breaking changes will only ship in a major-version bump, and this page will gain a ## vX.Y.Z section for each one, documenting exactly what changed and how to adapt.

Updating the npm package

If your project depends on @properui/ui as an npm package, update it the normal way:

npm install @properui/ui@latest

Or your package manager's equivalent (pnpm up @properui/ui, yarn up @properui/ui). Check the package's published release notes before upgrading across a major version.

Updating components you've copied in

The CLI copies component source directly into your project, so there's no dependency version to bump for those files: you update them by pulling in the current registry version. Start with diff to see what changed:

npx @properui/cli@latest diff              # every installed component
npx @properui/cli@latest diff button       # just one

diff compares your local files against the current registry version and shows exactly what's different, so you can decide whether to merge the change by hand or take the upstream file as-is. To take it as-is, re-run add with --overwrite:

npx @properui/cli@latest add button --overwrite

--overwrite replaces the local file entirely: it doesn't merge. Review the diff output first if you've customized the component, or you'll lose those edits.

What to expect from a future breaking change

There's no upgrade or migrate command today, and this page won't describe one until it ships. diff and add --overwrite are the tools available now for pulling changes into components you've already copied in. When the first breaking change lands:

• It will be documented here under a new ## vX.Y.Z heading, naming the specific class, prop, or structural change and how to update your code.
• diff will show you exactly which of your files are affected, since it always compares against the current registry content.
• For any file you haven't customized, add --overwrite will bring it fully up to date in one step.

FAQs