Next.js 13

Next.js 13 introduces a new app/ directory folder structure. By default it uses React Server Components. To use NextUI in those components, you need to convert them into client-side component by adding a
'use client'; at the top of your file. NextUI only works in client-side components.

Next.js 12 and below

If you're not using the new app/ directory, there's no need to add the 'use client'; directive, you just need to customize the _app.jsx entry file to load the provider. Here's an example project.

SSR Setup

In Next.js framework, you need to customize the pages/_document.js file. Then we add the following code to the file:

// pages/_document.js

import React from "react";
import Document, { Html, Head, Main, NextScript } from "next/document";
import { CssBaseline } from "@nextui-org/react";

class MyDocument extends Document {
  static async getInitialProps(ctx) {
    const initialProps = await Document.getInitialProps(ctx);
    return {
      styles: React.Children.toArray([initialProps.styles]),

  render() {
    return (
      <Html lang="en">
          <Main />
          <NextScript />

export default MyDocument;

Provider Setup

NextUI needs to be wrapped in a provider to work properly. You need to set up the NextUIProvider at the root of your application.

Go to pages/_app.js or pages/_app.tsx (create it if it doesn't exist) and add the following code:

// pages/_app.js

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

function MyApp({ Component, pageProps }) {
  // 2. Use at the root of your app
  return (
      <Component {...pageProps} />

export default MyApp

Cutomizing theme

If you intend to customise the default theme object to match your design requirements, you need to extend the theme.

NextUI provides a createTheme function that deep merges the default theme with your customizations.

// pages/_app.js

// 1. Import `createTheme`
import { createTheme, NextUIProvider } from "@nextui-org/react"

// 2. Call `createTheme` and pass your custom theme values
const theme = createTheme({
  type: "dark", // it could be "light" or "dark"
  theme: {
    colors: {
      primary: '#4ADE7B',
      secondary: '#F9CB80',
      error: '#FCC5D8',

// 3. Pass the new `theme`` to the `NextUIProvider`
function MyApp({ Component, pageProps }) {
  return (
    <NextUIProvider theme={theme}>
      <Component {...pageProps} />

export default MyApp

To futher customize the theme, please refer to the theming documentation.

gradient blue backgroundgradient violet background