Theme

Theming is a key element in designing user interfaces (UIs). It enables the application of a consistent aesthetic across your application, enhancing the user experience and maintaining visual uniformity.

In NextUI, we facilitate easy and flexible theme customization using a TailwindCSS plugin. This plugin, which is based on the tw-colors plugin developed by L-Blondy, allows you to customize color schemes, layout configurations, and more, across different components of your application.

What is a Theme?

A theme, in the context of NextUI, is a predefined set of colors, layout attributes, and other UI elements that you can consistently apply across your application. Themes ensure visual consistency, enrich the user experience, and simplify the management and updates of your app's look and feel.

Setup

The first step to using NextUI's theming capability is adding the nextui plugin to your tailwind.config.js file. Below is an example of how to do this:

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

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    // ...
    "./node_modules/@nextui-org/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  darkMode: "class",
  plugins: [nextui()],
};

Usage

After adding the plugin to your tailwind.config.js file, you can utilize any of the default themes (light/dark) or a custom one. Here's how you can apply these themes in your main.jsx or main.tsx:

Go to the src directory and inside main.jsx or main.tsx, apply the following class names to the root element:

light for the light theme.
dark for the dark theme.
text-foreground to set the text color.
bg-background to set the background color.

// main.tsx or 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")).render(
  <React.StrictMode>
    <NextUIProvider>
      <main className="dark text-foreground bg-background">
        <App />
      </main>
    </NextUIProvider>
  </React.StrictMode>,
);

Note: See the Colors section to learn more about the color classes.

Default Plugin Options

The nextui plugin provides a default structure. It is outlined as follows:

module.exports = {
  plugins: [
    nextui({
      prefix: "nextui", // prefix for themes variables
      addCommonColors: false, // override common colors (e.g. "blue", "green", "pink").
      defaultTheme: "light", // default theme from the themes object
      defaultExtendTheme: "light", // default theme to extend on custom themes
      layout: {}, // common layout tokens (applied to all themes)
      themes: {
        light: {
          layout: {}, // light theme layout tokens
          colors: {}, // light theme colors
        },
        dark: {
          layout: {}, // dark theme layout tokens
          colors: {}, // dark theme colors
        },
        // ... custom themes
      },
    }),
  ],
};

Themes Options

These are the options that you can use to apply custom configurations to your themes.

module.exports = {
  plugins: [
    nextui({
      themes: {
        light: {
          layout: {},
          colors: {}
        },
        dark: {
          layout: {},
          colors: {}
        },
        ... // custom themes
      }
    })
  ]
}

Nested themes

NextUI supports nested themes, allowing you to apply different themes to different sections of your application:

<html class="dark">
  ...
  <div class="light">...</div>
  <div class="purple-dark">...</div>
</html>

Theme based variants

NextUI enables you to apply TailwindCSS styles based on the currently active theme. Below are examples of how to do this:

<!-- In dark theme, background will be dark and text will be light. 
  In light theme, background will be light and text will be dark -->

<div class="dark dark:bg-gray-800 dark:text-white bg-white text-black">
  ...
  <div>Text color changes based on theme</div>
</div>

<div class="light light:bg-gray-100 light:text-black bg-black text-white">
  ...
  <div>Text color changes based on theme</div>
</div>

API Reference

The following table provides an overview of the various attributes you can use when working with themes in NextUI:

Attribute	Type	Description	Default
prefix	`string`	The prefix for the css variables.	`nextui`
addCommonColors	`boolean`	If true, the common nextui colors (e.g. "blue", "green", "purple") will replace the TailwindCSS default colors.	`false`
defaultTheme	`light` \| `dark`	The default theme to use.	`light`
defaultExtendTheme	`light` \| `dark`	The default theme to extend.	`light`
layout	LayoutTheme	The layout definitions.	-
themes	ConfigThemes	The theme definitions.	-

Types

ConfigThemes

type ConfigTheme = {
  extend?: "light" | "dark"; // base theme to extend
  layout?: LayoutTheme; // see LayoutTheme
  colors?: ThemeColors; // see ThemeColors
};

type ConfigThemes = Record<string, ConfigTheme>;

LayoutTheme

type BaseThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
};

type FontThemeUnit = {
  small?: string;
  medium?: string;
  large?: string;
  tiny?: string;
};

interface LayoutTheme {
  /**
   * Base unit token that defines a consistent spacing scale across
   * the components.
   */
  spacingUnit?: number;
  /**
   * The default font size applied across the components.
   */
  fontSize?: FontThemeUnit;
  /**
   * The default line height applied across the components.
   */
  lineHeight?: FontThemeUnit;
  /**
   * The default radius applied across the components.
   * we recommend to use `rem` units.
   */
  radius?: BaseThemeUnit;
  /**
   * A number between 0 and 1 that is applied as opacity-[value] when
   * the component is disabled.
   */
  disabledOpacity?: string | number;
  /**
   * The default height applied to the divider component.
   * we recommend to use `px` units.
   */
  dividerWeight?: string;
  /**
   * The border width applied across the components.
   */
  borderWidth?: BaseThemeUnit;
  /**
   * The box shadow applied across the components.
   */
  boxShadow?: BaseThemeUnit;
}

ThemeColors

type ColorScale = {
  50: string;
  100: string;
  200: string;
  300: string;
  400: string;
  500: string;
  600: string;
  700: string;
  800: string;
  900: string;
  foreground: string; // contrast color
  DEFAULT: string;
};

type BaseColors = {
  background: ColorScale; // the page background color
  foreground: ColorScale; // the page text color
  divider: ColorScale; // used for divider and single line border
  overlay: ColorScale; // used for modal, popover, etc.
  focus: ColorScale; // used for focus state outline
  content1: ColorScale; // used for card, modal, popover, etc.
  content2: ColorScale;
  content3: ColorScale;
  content4: ColorScale;
};

// brand colors
type ThemeColors = BaseColors & {
  default: ColorScale;
  primary: ColorScale;
  secondary: ColorScale;
  success: ColorScale;
  warning: ColorScale;
  danger: ColorScale;
};