# Dark Mode ยท HeroUI
> Add light, dark, and system theme switching to HeroUI v3
- Page: https://jiguang132.com/systems/heroui/docs/getting-started/dark-mode
- Based on: HeroUI documentation (Apache-2.0) @ 60edd8ed751b1d2a270623fbb182bbcfa8baa9af
HeroUI dark mode is CSS-driven. Components read theme variables from the root element, so you do not need a HeroUI provider. Add the `dark` class or `data-theme="dark"` to `` and HeroUI will apply the dark theme.
```html
```
Keep the `bg-background` and `text-foreground` classes on your app shell so the page canvas changes with the active theme.
>
HeroUI's built-in light and dark themes respond to both `.light` / `.dark` classes and `data-theme="light"` / `data-theme="dark"` attributes. If you set both manually, keep the values in sync.
## Next.js with next-themes
Use [next-themes](https://github.com/pacocoursey/next-themes) when you need theme persistence, system preference support, and no flash before hydration in a Next.js app.
### Install next-themes
#### npm
```bash
npm i next-themes
```
#### pnpm
```bash
pnpm add next-themes
```
#### yarn
```bash
yarn add next-themes
```
#### bun
```bash
bun add next-themes
```
### App Router
Create a client provider for `next-themes`.
```tsx
// app/providers.tsx
"use client";
import {ThemeProvider as NextThemesProvider} from "next-themes";
export function Providers({children}: {children: React.ReactNode}) {
return (
{children}
);
}
```
Wrap your app with the provider from the root layout. Add `suppressHydrationWarning` to `` because `next-themes` updates that element before hydration.
```tsx
// app/layout.tsx
import "./globals.css";
import {Providers} from "./providers";
export default function RootLayout({children}: {children: React.ReactNode}) {
return (
{children}
);
}
```
### Theme switcher
Use `useTheme` from `next-themes` inside a client component. Delay rendering until mount because the active theme is not known during SSR.
```tsx
// app/components/theme-switcher.tsx
"use client";
import {Button} from "@heroui/react";
import {useTheme} from "next-themes";
import {useEffect, useState} from "react";
export function ThemeSwitcher() {
const [mounted, setMounted] = useState(false);
const {resolvedTheme, setTheme, theme} = useTheme();
useEffect(() => {
setMounted(true);
}, []);
if (!mounted) return null;
const activeTheme = theme === "system" ? resolvedTheme : theme;
return (
);
}
```
### Pages Router
For `pages/`, wrap your application in `pages/_app.tsx`.
```tsx
// pages/_app.tsx
import "@/styles/globals.css";
import type {AppProps} from "next/app";
import {ThemeProvider as NextThemesProvider} from "next-themes";
export default function App({Component, pageProps}: AppProps) {
return (
);
}
```
## Using custom theme names
The `attribute="class"` setup works well for the built-in `light` and `dark` themes. If your custom theme CSS is written with `data-theme` selectors, configure `next-themes` to write `data-theme` instead.
```tsx
{children}
```
When you pass a custom `themes` list, include `"light"` and `"dark"` if you still want the built-in themes available.
## React with useTheme
Use HeroUI's `useTheme` hook when you are building a plain React app, such as Vite or Create React App, and do not need `next-themes`.
The hook is exported from `@heroui/react`. It stores the selected theme in `localStorage`, resolves `"system"` from the user's OS preference, and applies both the class and `data-theme` attribute to ``.
```tsx
// src/components/theme-switcher.tsx
import {Button, useTheme} from "@heroui/react";
export function ThemeSwitcher() {
const {resolvedTheme, setTheme, theme} = useTheme("system");
return (
);
}
```
>
Use one theme controller per app. In Next.js, prefer `next-themes` and its `useTheme` hook. In plain React apps, use `useTheme` from `@heroui/react`.
## Styling for both themes
Theme-aware utilities work automatically because they read CSS variables:
```tsx
Theme-aware content
```
Use the `dark:` variant for one-off changes that only apply in dark mode:
```tsx
Custom dark-mode adjustment
```
---
Index of all JGuang resources: https://jiguang132.com/llms.txt