Next.js

Requirements:

Next.js 12 or later
React 18 or later
Tailwind CSS 3.4 or later
Framer Motion 11 or later

To use NextUI in your Next.js project, you need to follow the steps below, depending on your project structure.

App Directory Setup

Next.js 13 introduces a new app/ directory structure. By default it uses Server Components. As NextUI components use React hooks, we added the use client; at build time, so you can import them directly in your React Server Components (RSC).

NextUI CLI (recommended)

If you are starting a new project, you can use the NextUI CLI to create a new project with NextUI pre-configured:

npm install -g nextui-cli

nextui init -t app

create-next-app

If you are starting a new project, you can run one of the following commands to create a Next.js project pre-configured with NextUI:

npx create-next-app -e https://github.com/nextui-org/next-app-template

Automatic Installation

You can add individual components using the CLI. For example, to add a button component:

nextui add button

This command adds the Button component to your project and manages all related dependencies.

You can also add multiple components at once:

nextui add button input

Or you can add the main library @nextui-org/react by running the following command:

nextui add --all

If you leave out the component name, the CLI will prompt you to select the components you want to add.

? Which components would you like to add? › - Space to select. Return to submit
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    [a,b,c]/delete: Filter choices
    enter/return: Complete answer

Filtered results for: Enter something to filter

◯  accordion
◯  autocomplete
◯  avatar
◯  badge
◯  breadcrumbs
◉  button
◯  card
◯  checkbox
◯  chip
◯  code

You still need to add the provider to your app manually (we are working on automating this step).

// app/providers.tsx

import {NextUIProvider} from '@nextui-org/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <NextUIProvider>
      {children}
    </NextUIProvider>
  )
}

// app/layout.tsx

// globals.css includes @tailwind directives
// adjust the path if necessary
import "@/styles/globals.css";
import {Providers} from "./providers";

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

Manual Installation

Add dependencies

In your Next.js project, run one of the following commands to install NextUI:

npm i @nextui-org/react framer-motion

Hoisted Dependencies Setup

Note: This step is only for those who use pnpm to install. If you install NextUI using other package managers, you may skip this step.

If you are using pnpm, you need to add the following line to your .npmrc file to hoist our packages to the root node_modules.

public-hoist-pattern[]=*@nextui-org/*

After modifying the .npmrc file, you need to run pnpm install again to ensure that the dependencies are installed correctly.

Tailwind CSS Setup

NextUI is built on top of Tailwind CSS, so you need to install Tailwind CSS first. You can follow the official installation guide to install Tailwind CSS. Then you need to add the following code to your tailwind.config.js file:

Note: If you are using pnpm and monorepo architecture, please make sure you are pointing to the ROOT node_modules

// tailwind.config.js
import {nextui} from "@nextui-org/react";

/** @type {import('tailwindcss').Config} */
const config = {
  content: [
    // ...
    // make sure it's pointing to the ROOT node_module
    "./node_modules/@nextui-org/theme/dist/**/*.{js,ts,jsx,tsx}"
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [nextui()]
}

export default config;

Setup Provider

Go to your app/providers.tsx or app/providers.jsx (create it if it doesn't exist) and wrap the Component with the NextUIProvider:

// app/providers.tsx
'use client'

import {NextUIProvider} from '@nextui-org/react'

export function Providers({children}: { children: React.ReactNode }) {
  return (
    <NextUIProvider>
      {children}
    </NextUIProvider>
  )
}

Add Provider to Root

Now, Go to your root layout page and wrap it with the Providers:

// app/layout.tsx

// globals.css includes @tailwind directives
// adjust the path if necessary
import "@/styles/globals.css";
import {Providers} from "./providers";

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

Note: NextUI automatically adds two themes, light and dark, to your application. You can use any of them by adding the dark/light class to the html tag. See the theme docs for more details.

Use NextUI Components

Now you can import any NextUI component directly in your Server Components without needing to use the use client; directive:

// app/page.tsx
import {Button} from '@nextui-org/button'; 

export default function Page() {
  return (
    <div>
      <Button>Click me</Button>
    </div>
  )
}

Important 🚨: Note that you need to import the component from the individual package, not from @nextui-org/react.

Pages Directory Setup