Installation

Installation

Execute one of the following commands in your terminal:

npm install -g nextui-cli

Initialization and Starting the App

Initialize the project by using the init command.

nextui init my-nextui-app

You will be prompted to configure your project:

◇  Select a template (Enter to select)
│  ● App (A Next.js 14 with app directory template pre-configured with NextUI (v2) and Tailwind CSS.)
│  ○ Pages (A Next.js 14 with pages directory template pre-configured with NextUI (v2) and Tailwind CSS.)
│  ○ Vite (A Vite template pre-configured with NextUI (v2) and Tailwind CSS.)

Install the dependencies to start the local server:

cd my-nextui-app && npm install

Start the local server:

npm run dev

Adding the Components

Once your NextUI project is ready to develop, 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

Install Packages

To install NextUI, run one of the following commands in your terminal:

npm install @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
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

It is essential to add the NextUIProvider at the root of your application.

import * as React from "react";

// 1. import `NextUIProvider` component
import {NextUIProvider} from "@nextui-org/react";

function App() {
  // 2. Wrap NextUIProvider at the root of your app
  return (
    <NextUIProvider>
      <YourApplication />
    </NextUIProvider>
  );
}

Install Core Packages

Although you can install each package separately, you need to install the core packages first to ensure that all components work correctly.

Run one of the following commands in your terminal to install the core packages:

npm install @nextui-org/theme @nextui-org/system framer-motion

Install Component

Now, let's install the component you want to use. For example, if you want to use the Button component, you need to run one of the following commands in your terminal:

npm install @nextui-org/button

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

TailwindCSS setup changes a bit when you use individual packages. You only need to add the styles of the components you're using to your tailwind.config.js file. For example, for the Button component, you need to add the following code to your tailwind.config.js file:

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // single component styles
    "./node_modules/@nextui-org/theme/dist/components/button.js",
    // or you can use a glob pattern (multiple component styles)
    './node_modules/@nextui-org/theme/dist/components/(button|snippet|code|input).js'
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [nextui()],
};

Provider Setup

It is essential to add the NextUIProvider at the root of your application.

import * as React from "react";

// 1. import `NextUIProvider` component
import {NextUIProvider} from "@nextui-org/system";

function App() {
  // 2. Wrap NextUIProvider at the root of your app
  return (
    <NextUIProvider>
      <YourApplication />
    </NextUIProvider>
  );
}

Use the Component

Now, you can use the component you installed in your application:

import * as React from "react";
import {Button} from "@nextui-org/button";

function App() {
  return (
    <Button>Press me</Button>
  );
}