HeroUI v3 Quick Start

HeroUI is a React component library built on Tailwind CSS v4 and React Aria Components. Every component comes with smooth animations, polished details, and built-in accessibility — ready to use, fully customizable.

This post is a condensed tour of the official Introduction and Quick Start — why HeroUI v3 is worth adopting, and everything you need to drop a HeroUI button into a fresh React project.

Why HeroUI?

Beautiful by default — professional look out of the box, no extra styling needed.
Accessible — built on React Aria Components with focus management, keyboard navigation, and screen reader support.
Flexible — every component is made of customizable parts. Change what you need, leave the rest.
Developer-friendly — fully typed APIs, predictable patterns, and excellent autocompletion.
Maintained — updates, bug fixes, and new features ship on the package. No vendored snapshots to babysit.
Lightweight — fully tree-shaken. Only what you import ends up in your bundle.
Future-proof — built for React 19 and Tailwind v4, and designed for AI-assisted development.

A living library, not copy-paste

Copy-paste component kits work until they break. You end up maintaining outdated dependencies that have stopped evolving.

HeroUI is different. It's a library that grows with you:

Automatic updates and fixes through @heroui/react
New features without touching your component folder
Stays current with React, Tailwind, and browsers
Deep customization via CSS variables and BEM slots, not shallow theme tweaks
AI-friendly APIs for code generation

Requirements

Both are non-negotiable. v3 leans on React 19 APIs (use, ref-as-prop) and Tailwind v4's zero-config token pipeline. Running it on React 18 or Tailwind v3 will fail loudly.

Install

Install HeroUI and its required dependencies. pnpm is my daily driver, but the other three work identically.

pnpm add @heroui/styles @heroui/react

npm i @heroui/styles @heroui/react

yarn add @heroui/styles @heroui/react

bun add @heroui/styles @heroui/react

No provider to wire up. HeroUI v3 dropped the <HeroUIProvider> wrapper — theming lives entirely in CSS variables.

Import styles

Add both imports to your main CSS file (e.g. app/globals.css):

app/globals.css

@import "tailwindcss";
@import "@heroui/styles";

Import order matters. Load tailwindcss first so HeroUI can layer its utilities on top; swap them and HeroUI's design tokens will lose to Tailwind's defaults.

Use a component

app/page.tsx

import { Button } from "@heroui/react";

export default function Home() {
  return <Button>My Button</Button>;
}

That's the whole flow. No context providers, no theme object, no framer-motion dependency. Dark mode is a single class on <html> and every HeroUI component picks it up.

Framework notes

For Next.js App Router, the canonical setup is:

app/layout.tsx

import "./globals.css";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>{children}</body>
    </html>
  );
}

suppressHydrationWarning is there so a theme-toggle script can mutate <html class="dark"> before React hydrates without screaming at you.

What I'd reach for next

Themes — HeroUI uses oklch() color variables. Override four CSS variables and you have a branded UI.
Compound patterns — every v3 component uses dot-notation subcomponents (Card.Header, Tabs.Tab). Lean into them instead of fighting for flat props.
Styling — Tailwind arbitrary values work inline; @layer components lets you retheme BEM classes globally when inline utilities get noisy.
Components index — browse the full catalog on the components page.

Total install-to-running time on my machine: just under four minutes. Hard to beat.

FAQ

Is HeroUI free? Yes — completely free and open source under the Apache License 2.0.

Is it production-ready? Yes. HeroUI v3 is stable and ready for production.

Can I customize the components? Yes. Use Tailwind utilities, CSS variables, BEM modifiers, or compose component parts differently. Every slot is customizable.

Does it work with TypeScript? Fully typed with excellent IDE support and autocompletion.

What about accessibility? Built on React Aria Components for WCAG compliance. Keyboard navigation, focus management, and screen reader support are included.

Can I use the styles without React? Yes — @heroui/styles can be applied to plain HTML. See HeroUI's Tailwind Play example.

Is there a Figma file? Yes — HeroUI Figma Kit V3.

HeroUI ecosystem

HeroUI v3 (web) — what this post covers: React components with Tailwind CSS v4.
HeroUI Native — React Native components with the same design language.
HeroUI Chat — text-to-app, build UIs with natural language.
UI for LLMs — new platform and MCPs announced, not yet shipped.

Get involved

HeroUI is released under the Apache License 2.0.

On this page