Upgrade to v2

Requirements:

React 18 or later
Tailwind CSS 3.4 or later
Framer Motion 11 or later

Next.js upgrade steps

Make sure to follow the previous steps since they are required to upgrade to v2.

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).

Installation

In your Next.js project, run one of the following command 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:

// tailwind.config.js
const { nextui } = require("@nextui-org/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  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()]
}

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 NextUIProvider:

// app/layout.tsx
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 add 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 the from @nextui-org/react.

Pages Directory Setup

Installation

In your Next.js project, run one of the following command 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

// tailwind.config.js
const { nextui } = require("@nextui-org/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  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()]
}

Setup Provider

Go to pages/_app.js or pages/_app.tsx (create it if it doesn't exist) and wrap the Component with the NextUIProvider:

// pages/_app.js
import {NextUIProvider} from '@nextui-org/react'

function MyApp({ Component, pageProps }) {
  return (
    <NextUIProvider>
      <Component {...pageProps} />
    </NextUIProvider>
  )
}

export default MyApp;

Use NextUI Components

Now you can import any NextUI component wherever you want:

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

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

React upgrade steps

Upgrade React version

NextUI v2 requires React 18 or later. To upgrade React, run the following command:

npm i react@latest react-dom@latest

Install Framer motion

In v2, NextUI now requires framer-motion as a dependency. To install both, use the following command:

npm i 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.

TailwindCSS Setup

NextUI v2 now uses Tailwind CSS. Add the NextUI plugin 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
const { nextui } = require("@nextui-org/react");

/** @type {import('tailwindcss').Config} */
module.exports = {
  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()]
}

Provider Setup

Go to root file and wrap the Component with the NextUIProvider:

// src/main.jsx
import React from 'react'
import ReactDOM from 'react-dom/client'
import {NextUIProvider} from '@nextui-org/react'
import App from './App'
import './index.css'

ReactDOM.createRoot(document.getElementById('root') as HTMLElement).render(
  <React.StrictMode>
    <NextUIProvider>
      <App />
    </NextUIProvider>
  </React.StrictMode>,
)

Use NextUI Components

Now you can import any NextUI component wherever you want:

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

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

Please visit the Release Notes for more information about the new features and breaking changes.