What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
For a new React app, the current HeroUI v3 quick start calls for React 19 or later and Tailwind CSS v4. Install @heroui/styles and @heroui/react, import Tailwind before HeroUI’s styles in your main CSS file, then import the component you need from @heroui/react. Existing projects need a different path: renaming NextUI packages to HeroUI is not the same as upgrading HeroUI v2 to v3.
Set up HeroUI v3 in a new React project
These instructions follow the current HeroUI Quick Start. Check that your app uses React 19 or later and Tailwind CSS v4 before installing; older v2 instructions use a different styling setup.
- Install the packages. From your project directory, run
npm i @heroui/styles @heroui/react. Use the equivalent install command for your package manager if you do not use npm. - Update the main stylesheet. Add the imports in this order:
@import "tailwindcss"; @import "@heroui/styles";Tailwind must be imported before HeroUI styles.
- Import and render a component. For example, in a React component:
import { Button } from '@heroui/react'; function App() { return <Button>My Button</Button>; }
Use the v3 quick start as the reference for additional setup and components. Do not combine these instructions with older v2 configuration: the v3 migration guide says v3 does not require HeroUIProvider.
Choose the right migration path for an existing app
First identify whether the project still uses NextUI packages or already uses HeroUI v2. The package rename and the v2-to-v3 upgrade are separate tasks with different scope.
Recommended Free Tools
#1 Best Overall
| Starting point | What changes | Recommended approach |
|---|---|---|
NextUI using @nextui-org/* |
Brand and package migration to @heroui/*, including imports and related configuration. |
Use the NextUI-to-HeroUI codemod, install dependencies, and verify the app. |
| HeroUI v2 | Breaking upgrade involving React and Tailwind requirements, styling, components, hooks, and APIs. | Use the full migration guide and do the work on a feature branch. |
Move from NextUI to HeroUI
The NextUI to HeroUI guide recommends running npx @heroui/codemod@latest migrate. In a monorepo, run the command from the repository root. The codemod updates package names, component imports and references, Tailwind configuration, provider components, and NextUI-specific utilities or hooks.
- Run the codemod from the project directory (or monorepo root).
- Run your package manager’s install command to install the updated dependencies.
- Check that components render, theme customizations remain intact, no NextUI imports remain, and the app builds.
Treat the codemod as an aid, not a guarantee that every project-specific change is complete. Review the resulting changes and fix issues your app or custom code still has.
Upgrade HeroUI v2 to v3
This is a breaking migration, not a package rename. HeroUI’s Full Migration guide warns that v2 and v3 cannot coexist during a full migration and that the project will be broken while the migration is in progress. Work on a feature branch so the main branch remains usable.
Prepare and migrate component code
Follow the official guide’s sequence: migrate component code while the project still has v2 dependencies, then switch dependencies and resolve remaining issues. During the transition, use typecheck and lint as interim checks; the guide’s initial workflow says not to build or run the app while it is intentionally in a broken intermediate state.
Update dependencies and styling
The v3 migration requires React 19 or later and Tailwind CSS v4. Add @heroui/styles alongside @heroui/react, remove Framer Motion and the heroui() Tailwind plugin setup, and use the CSS imports shown in the new-project setup, with Tailwind first. The v3 guide also says HeroUIProvider is no longer required.
Review API and component changes
Expect more than dependency edits. The guide describes compound-component patterns, changed or removed hooks, styling-token changes, renamed components, and components removed from v3. Examples of renamed components include:
DividerbecomesSeparator.AutocompletebecomesCombobox.NumberInputbecomesNumberField.
Components listed as removed include Code, Image, Navbar, Ripple, Snippet, Spacer, and User. Where appropriate, replace them with standard HTML elements. Consult the migration reference for each component your app uses rather than assuming that a renamed component has an identical API.
Test after the migration is complete
Once dependencies and component code have been migrated, test the completed application for functionality, accessibility, responsive behavior, visual differences, and performance. This is distinct from checks during the broken intermediate phase: wait until the migration is complete before trying to run or build the app according to the guide’s workflow.
Best Value
Keep version-specific instructions separate
HeroUI v2 and v3 do not share one setup recipe. V2 projects use the older styling plugin/configuration and HeroUIProvider; v3 uses @heroui/styles, Tailwind v4 CSS imports, and does not require that provider. Confirm your installed version before copying configuration or migration steps, and use the corresponding official guide.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
