Installation

Step-by-step guide to setting up HeroUI v3 with Next.js 16.

Prerequisites

  • Node.js 18.17 or later
  • Next.js 16 with App Router
  • Tailwind CSS v4
  • A package manager (yarn recommended)

1. Install HeroUI

yarn add @heroui/react

2. Configure next.config.js

// next.config.js
module.exports = {
  transpilePackages: ['@heroui/react'],
}

3. Add Component Styles

HeroUI v3 beta requires manual CSS for components. Add these styles to your globals.css:

/* globals.css */
@import 'tailwindcss';

/* HeroUI Button styles */
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  font-weight: 500;
  border-radius: var(--radius);
  transition: all 150ms ease;
  cursor: pointer;
}

.button--primary {
  background-color: var(--color-primary);
  color: var(--color-primary-foreground);
}
/* ... more styles */

4. Use Components

import { Button, Card, Chip } from "@neo/test-components"

export default function Page() {
  return (
    <Card>
      <Chip>New</Chip>
      <Button variant="primary">Click me</Button>
    </Card>
  )
}

Server Component Support

HeroUI v3 is built on React Aria Components and is designed to work with React Server Components. Most components can be rendered on the server without the "use client" directive.

Interactive components (like dialogs, dropdowns, tooltips) require client components for event handling and state management.

This page is a Server Component — HeroUI is RSC-compatible.