Installation

Requirements

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

Login

Run the HeroUI Pro CLI and log in with your GitHub account:

npx heroui-pro@latest login

bunx heroui-pro@latest login

pnpm dlx heroui-pro@latest login

A browser tab will open automatically. Sign in with your GitHub account, authorize the application, and wait for the terminal to confirm:

Logged in as @your-username

Install

Once logged in, run:

npx heroui-pro@latest install

bunx heroui-pro@latest install

pnpm dlx heroui-pro@latest install

The CLI handles everything automatically:

1. Adds @heroui-pro/react to your project (if not already present)
2. Downloads Pro components from the CDN using your license
3. Detects missing peer dependencies and installs them with the correct version ranges
4. Configures your package manager — for pnpm and bun, offers to allowlist the postinstall script so future installs work seamlessly

You'll see an interactive prompt to confirm which peer dependencies to install. Press Enter to install all of them:

◆  Missing peer dependencies detected. Press Enter to install all, or uncheck to skip:
│  ↑↓ move, space select, enter confirm
│  ◼ @heroui/react (>=3.2.2)
│  ◼ @heroui/styles (>=3.2.2)
│  ◼ tailwindcss (>=4.0.0)
│  ...

After installation completes you'll see:

└  ✓ HeroUI React Pro installed successfully.

Import Styles

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

@import "tailwindcss";
@import "@heroui/styles";
@import "@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>
  );
}

SSR and subpath imports

Most components are re-exported from the package root, so you can import them from the barrel:

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

Some components rely on heavy, opt-in peer dependencies and are not exported from the barrel. Import them from their subpaths instead:

import { Map } from '@heroui-pro/react/map';                       // requires maplibre-gl
import { Markdown } from '@heroui-pro/react/markdown';             // requires streamdown, react-markdown, marked, remark-*
import { RichTextEditor } from '@heroui-pro/react/rich-text-editor'; // requires @tiptap/*

// Charts + KPI require recharts
import { AreaChart } from '@heroui-pro/react/area-chart';
import { BarChart } from '@heroui-pro/react/bar-chart';
import { LineChart } from '@heroui-pro/react/line-chart';
import { PieChart } from '@heroui-pro/react/pie-chart';
import { ComposedChart } from '@heroui-pro/react/composed-chart';
import { RadarChart } from '@heroui-pro/react/radar-chart';
import { RadialChart } from '@heroui-pro/react/radial-chart';
import { KPI } from '@heroui-pro/react/kpi';

import { Carousel } from '@heroui-pro/react/carousel';             // requires embla-carousel(-react)
import { CodeBlock } from '@heroui-pro/react/code-block';          // requires shiki
import { ChatTool } from '@heroui-pro/react/chat-tool';            // requires shiki (via Code Block)
import { NumberStepper } from '@heroui-pro/react/number-stepper';  // requires @number-flow/react
import { Resizable } from '@heroui-pro/react/resizable';           // requires react-resizable-panels

Subpath imports also tree-shake cleanly, so they're a good default even outside SSR.

CLI Reference

CI/CD

For automated environments (GitHub Actions, Vercel, Netlify, etc.), use a CI/CD token instead of interactive login. Get your token from the dashboard.

Set the HEROUI_AUTH_TOKEN environment variable in your CI pipeline:

env:
  HEROUI_AUTH_TOKEN: ${{ secrets.HEROUI_AUTH_TOKEN }}

export HEROUI_AUTH_TOKEN=your-cicd-token
npm install

When HEROUI_AUTH_TOKEN is set, the postinstall script automatically authenticates and downloads Pro artifacts — no interactive login needed. This works with all package managers.

Verify Installation

After installation, verify everything is working:

1. Check that your app starts without errors
2. Try importing and using a Pro component like Command or Sheet
3. Run the CLI to check your status:

npx heroui-pro status

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.

pnpm or bun: postinstall didn't run

The CLI handles this automatically — heroui-pro install downloads artifacts directly and offers to configure your package.json so future installs work natively. If you prefer to configure it manually:

• bun: add "trustedDependencies": ["heroui-pro", "@heroui-pro/react"] to package.json
• pnpm: add "pnpm": { "onlyBuiltDependencies": ["heroui-pro", "@heroui-pro/react"] } to package.json

Yarn Berry (PnP) not supported

HeroUI Pro requires node_modules. If using Yarn Berry, add nodeLinker: node-modules to your .yarnrc.yml.

Authentication expired

Run npx heroui-pro login 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
• Design Systems — Create and share your own themes
• Colors — Understand the color system
• Pro UI for Agents — Set up AI tools for HeroUI Pro