Skip to content

docs: add Tailwind v4 data-theme styling guidance #395

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
luisangelrod wants to merge 2 commits into
base: main
Choose a base branch
from
+30 −0
Open

docs: add Tailwind v4 data-theme styling guidance #395

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
7a94516
docs: add Tailwind v4 data-theme approach that avoids hydration mismatch
luisangelrod Jun 24, 2026
13aa359
docs: clarify Tailwind hydration guidance
luisangelrod Aug 18, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions next-themes/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -537,6 +537,36 @@ Now set the attribute for your ThemeProvider to `data-mode`:

With this setup, you can now use Tailwind's dark mode classes, as in the previous example:

#### Tailwind v4 with data attributes

Tailwind v4 uses CSS `@custom-variant` instead of a `tailwind.config.js` file. You can configure dark mode to match the `data-theme` attribute on the `html` element, which is the **default** attribute that next-themes sets. The injected script updates this attribute in the browser before hydration, so Tailwind can apply the correct CSS without your components branching on `useTheme`.

In your global CSS file, add:

```css
/* globals.css */
@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
```

Leave the `ThemeProvider` at its default (no `attribute` prop needed), and keep `suppressHydrationWarning` on the `html` element because next-themes updates that element:

```tsx
// app/layout.tsx
<html suppressHydrationWarning>
<body>
<ThemeProvider>{children}</ThemeProvider>
</body>
</html>
```

Now use Tailwind dark-mode classes normally:

```tsx
<h1 className="text-black dark:text-white">Hello</h1>
```

> **Note:** This avoids the `mounted` guard for CSS-only theme styling because the rendered class names are the same on the server and client. If a value from `useTheme` changes the rendered markup, continue to use the [mounted pattern](#avoid-hydration-mismatch).

## Discussion

### The Flash
Expand Down
Loading