Migrate to v2

Web controlsCopy Anchor Link

Upgrade the runtime to uitheme-web@latest. Keep providers, hooks, theme values, storage keys, and callbacks. Test the saved appearance and palette before and after the upgrade.

Styled controls are no longer exported by the v2 runtime. Install the controls as editable source with uitheme-cli, then change imports to your local files. The runtime does not depend on Base UI, Radix, or Reka.

npx uitheme-cli migrate --dry-run
pnpm add uitheme-web@latest
npx uitheme-cli add theme-toggle theme-selector color-theme-selector --base base-ui
npx uitheme-cli migrate --dry-run

Use your app’s package manager for the dependency upgrade. Work on a migration branch. The app can have unresolved imports until you finish replacing the old controls. add requires v2 and does not run on an installed v1 runtime. For controls without custom props inside a recognized provider, review the migration preview. Apply the migration with npx uitheme-cli migrate --yes. Controls with custom props or unrecognized providers need manual changes. The command reports these cases before it writes files.

Choose --base radix for Radix React controls. Vue uses --base reka. Select the Tailwind major already used by the app with --tailwind 3 or --tailwind 4. The installed files use the selected base. They do not switch bases at runtime.

Replace the previous packaged control imports with the installed paths:

import { ThemeToggle } from '@/components/ui/theme-toggle';
import { ThemeSelector } from '@/components/ui/theme-selector';

Check the destinations in uitheme.json if your app uses another alias or component directory. Preserve customized controls until you have reviewed and tested their replacements. --yes does not overwrite edits.

Vue v1Copy Anchor Link

The published uitheme-vue@1 package remains available. There is no compatibility package. To adopt v2, install uitheme-web@latest and move Vue runtime imports to uitheme-web/vue. Use uitheme-web/vue/bootstrap for server bootstrap. Replace styled controls with local Reka source installed by uitheme-cli.

For Nuxt 4, replace the previous Vue module entry with uitheme-web/nuxt. Nuxt 3 automatic migration is not supported. Review framework compatibility before changing the Nuxt module.

Verify the appCopy Anchor Link

Check appearance and palette persistence after reload. Check the initial server HTML and hydration with light, dark, and system preferences. Check both transition directions and reduced motion. Check selector keyboard navigation, translated labels, and the duration value. Set transition style and duration on each control with animationType and duration props.