Installation

Requirements

React 19+
Tailwind CSS v4
HeroUI OSS (@heroui/react + @heroui/styles)

If you haven't set up HeroUI OSS yet, follow the HeroUI Quick Start first.

Add the Pro Package

Add @heroui-pro/react to your project dependencies:

package.json

{
  "dependencies": {
    "@heroui-pro/react": "latest"
  }
}

Install Peer Dependencies

HeroUI Pro requires the following peer dependencies. Install any you don't already have:

npm i @heroui/react @heroui/styles @number-flow/react motion react-aria-components recharts tailwind-merge tailwind-variants tailwindcss

pnpm add @heroui/react @heroui/styles @number-flow/react motion react-aria-components recharts tailwind-merge tailwind-variants tailwindcss

yarn add @heroui/react @heroui/styles @number-flow/react motion react-aria-components recharts tailwind-merge tailwind-variants tailwindcss

bun add @heroui/react @heroui/styles @number-flow/react motion react-aria-components recharts tailwind-merge tailwind-variants tailwindcss

Authenticate with GitHub

Run the HeroUI Pro CLI to authenticate:

npx heroui-pro

bunx heroui-pro

You'll see the following menu:

  _   _                _   _ ___   ____
 | | | | ___ _ __ ___ | | | |_ _| |  _ \ _ __ ___
 | |_| |/ _ \ '__/ _ \| | | || |  | |_) | '__/ _ \
 |  _  |  __/ | | (_) | |_| || |  |  __/| | | (_) |
 |_| |_|\___|_|  \___/ \___/|___| |_|   |_|  \___/

No HeroUI packages detected in this project.

? What would you like to do?
> Login with Github
  Buy HeroUI Pro
  Open HeroUI docs
  Exit

Select "Login with Github":

A browser tab will automatically open
Sign in with your GitHub account
Authorize the application
Wait for the success message: "You can close this tab and return to the terminal."

After successful authentication, you'll see:

? Hello @your-username, what would you like to do?
  Your session is valid for the next 179 days
────────────────────────────────────────────
> Manage your account
  Install HeroUI React Pro
  Logout
  Exit

Install HeroUI React Pro

From the CLI menu, select "Install HeroUI React Pro":

? Hello @your-username, what would you like to do?
  Your session is valid for the next 179 days
────────────────────────────────────────────
  Manage your account
> Install HeroUI React Pro
  Logout
  Exit

The CLI will automatically fetch and install the HeroUI Pro package from the CDN. The installation process handles version compatibility, ensuring you get the correct Pro version for your CLI.

Import Styles

Add HeroUI Pro styles to your main CSS file (e.g. globals.css):

globals.css

@import "tailwindcss";
@import "@heroui/styles";
@import "@heroui-pro/react/css";

Import order matters. Always import tailwindcss first, then @heroui/styles, then @heroui-pro/react/css.

Use a Pro Component

import { Command } from '@heroui-pro/react';

function App() {
  return (
    <Command>
      <Command.Backdrop />
      <Command.Container>
        <Command.Dialog>
          <Command.InputGroup>
            <Command.InputGroup.Input placeholder="Type a command..." />
          </Command.InputGroup>
          <Command.List>
            <Command.Item id="profile">Profile</Command.Item>
            <Command.Item id="settings">Settings</Command.Item>
            <Command.Item id="logout">Logout</Command.Item>
          </Command.List>
        </Command.Dialog>
      </Command.Container>
    </Command>
  );
}

Whitelisting Postinstall Scripts

Some package managers block postinstall scripts by default for security reasons. HeroUI Pro uses a postinstall script to download and install the package automatically. If the installation fails, you may need to whitelist it.

Bun blocks postinstall scripts by default. Add to your package.json:

package.json

{
  "trustedDependencies": ["@heroui-pro/react"]
}

pnpm may block postinstall scripts. Add to your .npmrc:

.npmrc

side-effects-cache=true

Or run the install with the --ignore-scripts=false flag:

pnpm install --ignore-scripts=false

Yarn v2+ blocks postinstall scripts by default. Add to your .yarnrc.yml:

.yarnrc.yml

enableScripts: true

npm allows postinstall scripts by default. If you've disabled them globally, re-enable with:

npm config set ignore-scripts false

If postinstall scripts don't run, HeroUI Pro may fail to initialize correctly. You'll see errors about missing modules or the package not being found.

Verify Installation

After installation, verify everything is working:

Check that your app starts without errors
Try importing and using a Pro component like Command or Sheet
Run the CLI again to verify your license status:

npx heroui-pro

Troubleshooting

Installation fails with permission errors

Try running the CLI with elevated permissions or check that your package manager has write access to node_modules.

Postinstall script doesn't run

See the Whitelisting Postinstall Scripts section above. Most issues are caused by package managers blocking scripts.

Authentication expired

Run npx heroui-pro again and select "Login with Github" to re-authenticate. Sessions are valid for 180 days.

Still having issues? Contact support@heroui.pro or reach out via live chat at heroui.pro/dashboard.

What's Next?

Browse Components — See all available Pro components
Theme Builder — Create and share your own themes
Colors — Understand the color system
Pro UI for Agents — Set up AI tools for HeroUI Pro

On this page