Frameworks

Next.js

1. Create a Next.js project

npx heroui-cli@latest init

When prompted, select the App or Pages template. Then open your new folder and install dependencies (for example pnpm install).

2. Use your first HeroUI component

Example: app/page.tsx

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

export default function HomePage() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <Button variant="tertiary">Hello HeroUI</Button>
    </main>
  );
}

Example: pages/index.tsx

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

export default function HomePage() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <Button variant="tertiary">Hello HeroUI</Button>
    </main>
  );
}

HeroUI v3 does not require a provider. Components work directly after installation and style import.

3 Locale Setup (Optional)

To integrate with Next.js, ensure the locale on the server matches the client.

In your root layout, determine the user's preferred language and set the lang and dir attributes on the <html> element.

// app/layout.tsx
import {headers} from 'next/headers';
import {isRTL} from '@heroui/react';
import {ClientProviders} from './provider';

export default async function RootLayout({children}) {
  // Get the user's preferred language from the Accept-Language header.
  // You could also get this from a database, URL param, etc.
  const acceptLanguage = (await headers()).get('accept-language');
  const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US';

  return (
    <html lang={lang} dir={isRTL(lang) ? 'rtl' : 'ltr'}>
      <body>
        <ClientProviders lang={lang}>
          {children}
        </ClientProviders>
      </body>
    </html>
  );
}

Create app/provider.tsx. This should render an I18nProvider to set the locale used by React Aria.

// app/provider.tsx
"use client";

import {I18nProvider} from '@heroui/react';

export function ClientProviders({lang, children}) {
  return (
    <I18nProvider locale={lang}>
      {children}
    </I18nProvider>
  );
}

If you are using a Content Security Policy (CSP) with a nonce, add a <meta property="csp-nonce"> tag to your document head, setting the content attribute to the generated nonce value. React Aria automatically reads the nonce from this tag.

Vite

1. Create a Vite project

npx heroui-cli@latest init

When prompted, select the Vite template. Then open your new folder and install dependencies (for example pnpm install).

2. Use your first HeroUI component

Example: src/App.tsx

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

function App() {
  return (
    <main className="flex min-h-screen items-center justify-center">
      <Button variant="tertiary">Hello HeroUI</Button>
    </main>
  );
}

export default App;

HeroUI v3 does not require a provider. Components work directly after installation and style import.

Next steps

Quick Start for the fastest setup path
Themes to customize colors and tokens
Components to explore all available components

On this page