Add option to opt-out of automatic script insertion #353

plmrry · 2025-04-17T18:31:14Z

Problem

We've seen a bug in Chrome where (in dark mode) there is a flash of light-themed code.

This appears to be due to how next-themes inserts <ThemeScript /> into the <body />

Solution

This PR:

Adds an optional withScript prop to <Theme>.

This allows the user to optionally disable the insertion of <ThemeScript> by setting withScript to false.
withScript defaults to true, which preserves the default behavior of next-themes.

Exports <ThemeScript>, so it can be manually inserted by the user (i.e. in the <head>)
Adds an optional string id prop that gets added to the script itself

Example

This is pseudo-code:

import { ThemeProvider, ThemeScript } from 'next-themes'

export default function RootLayout({
  children
}): JSX.Element {
  return (
    <html>
      <head>
        <ThemeScript storageKey="my-theme" />
      </head>
      <body>
        <ThemeProvider storageKey="my-theme" withScript={false}>
        {children}
      </body>
    </html>
  )
}

Based on internal work from @cramforce:

This appears to fix a long-standing bug where you get a flash of light-theme in Chrome.

The primary change in the fork is to allow placing the inline script manually. With the default-usage of next-themes, the script always goes into the body (usually first).

…avoid `disableAnimation` if not needed

next-themes/src/index.tsx

Co-authored-by: Steven <[email protected]>

…lmrry/next-themes into plmrry/add-script-document-head-option

plmrry · 2025-04-27T12:35:54Z

next-themes/src/index.tsx

@@ -32,6 +32,7 @@ export const ThemeProvider = (props: ThemeProviderProps) => {
 const defaultThemes = ['light', 'dark']

 const Theme = ({
+  withScript = true,


new prop that allows us to bypass mounting the script when set to false

next-themes/src/index.tsx

plmrry · 2025-04-27T12:36:31Z

next-themes/src/index.tsx

-        }}
-      />
-
+      {withScript ? (


here's where withScript determines if we should mount the script

plmrry · 2025-04-27T12:36:43Z

next-themes/src/index.tsx

      {children}
    </ThemeContext.Provider>
  )
 }

-const ThemeScript = React.memo(
+export const ThemeScript = React.memo(


export ThemeScript for manual placement

next-themes/src/index.tsx

styfle

Is this id necessary? We already have scriptProps

next-themes/src/index.tsx

plmrry · 2025-04-27T15:03:18Z

@styfle I removed that unnecessary id prop and added a unit test

plmrry · 2025-04-27T16:02:21Z

next-themes/__tests__/index.test.tsx

+  document.documentElement.removeAttribute('data-theme-test')
+  document.documentElement.removeAttribute('data-example')


This is un-related, but I noticed these need to be removed

next-themes/src/types.ts

Co-authored-by: Steven <[email protected]>

styfle

LGTM, thanks! 🎉

@pacocoursey Can you take another look?

pacocoursey · 2025-05-01T17:20:35Z

next-themes/src/index.tsx

Thanks for this, the PR looks quite succinct now. However I'm not sure this is a good approach – you're basically adding a feature that allows consumers to shoot themselves in the foot and not have perfect dark mode as this library advertises.

Could you elaborate on the issues you experienced with flashing on Chrome? Is this due to the script not being injected in the <head> element? If so, ideally the library can be fixed to inject into the head instead by using next/link with beforeHydration option. This way everyone that uses it will have correct behavior out of the box –– the whole point of this library.

In the past, next/script was quite buggy and this option didn't work reliably. But that was 2+ years ago so maybe it's viable to do it again.

Thanks for the feedback.

To be honest, this PR is just relaying work by @cramforce that was done internally. I need to dig into the original bug a bit more.

If so, ideally the library can be fixed to inject into the head instead by using next/link with beforeHydration option.

Would this mean adding next as a dependency? Happy to do this if that's what you mean.

Thanks, it'd be helpful to know more about the root issue. And yes, we can bring back next as a peerDep. It is next-themes, after all.

But we could also offer the option to export the script standalone as this PR already does.

@pacocoursey I'm working on a repro of the original issue, but in the meantime I created a tiny PR to export <ThemeScript>:

#355

plmrry added 4 commits April 17, 2025 14:30

Add opt-out of script insertion from provider, various type updates, …

d48dd7b

…avoid `disableAnimation` if not needed

reduce formatting diffs

c3de8d9

reduce more formatting diffs

873d3fa

handle multiple attributes in isThemeCurrentTheme

520d786

plmrry changed the title ~~Work In Progress: Opt-out of script insertion~~ Add option to opt-out of automatic script insertion Apr 17, 2025

plmrry marked this pull request as ready for review April 17, 2025 19:14

plmrry marked this pull request as draft April 17, 2025 19:42

plmrry added 2 commits April 17, 2025 15:43

export <ThemeScript />

6b9a53f

Update types.ts

d01248e

plmrry marked this pull request as ready for review April 17, 2025 19:53

styfle reviewed Apr 24, 2025

View reviewed changes

next-themes/src/index.tsx Outdated Show resolved Hide resolved

plmrry and others added 8 commits April 24, 2025 10:52

Update index.tsx

30f9670

Co-authored-by: Steven <[email protected]>

reduce diff; make script id optional

36c587b

Merge branch 'plmrry/add-script-document-head-option' of github.com:p…

365f18d

…lmrry/next-themes into plmrry/add-script-document-head-option

reduce the diff

2769dc7

revert more changes

a672429

more diff reduction

37f6ea8

reduce the diff again

8d9685e

pass optional ID from parent

796f786

plmrry commented Apr 27, 2025

View reviewed changes

next-themes/src/index.tsx Outdated Show resolved Hide resolved

plmrry commented Apr 27, 2025

View reviewed changes

next-themes/src/index.tsx

}}

/>

{withScript ? (

Copy link

Author

plmrry Apr 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

here's where withScript determines if we should mount the script

plmrry commented Apr 27, 2025

View reviewed changes

next-themes/src/index.tsx Outdated Show resolved Hide resolved

plmrry requested a review from styfle April 27, 2025 12:40

styfle reviewed Apr 27, 2025

View reviewed changes

next-themes/src/index.tsx Outdated Show resolved Hide resolved

plmrry added 2 commits April 27, 2025 10:46

remove unnecessary id

94f9b31

add tests of withScript=false and manual <ThemeScript> insertion

f6b9f62

formatting

b85091b

plmrry added 5 commits April 27, 2025 11:05

more formatting tweaks

ceb37c5

remove useless test

f22d92d

remove more attributes before each test

d3f7b2d

move withScript test

38f796f

remove unused import

f077f5a

plmrry commented Apr 27, 2025

View reviewed changes

plmrry requested a review from styfle April 27, 2025 16:02

styfle reviewed Apr 28, 2025

View reviewed changes

next-themes/src/types.ts Outdated Show resolved Hide resolved

Update next-themes/src/types.ts with better comment

3b87f0a

Co-authored-by: Steven <[email protected]>

styfle approved these changes Apr 28, 2025

View reviewed changes

plmrry requested a review from styfle April 28, 2025 19:24

pacocoursey reviewed May 1, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add option to opt-out of automatic script insertion #353

Add option to opt-out of automatic script insertion #353

plmrry commented Apr 17, 2025 •

edited

Loading

plmrry Apr 27, 2025

plmrry Apr 27, 2025

plmrry Apr 27, 2025

styfle left a comment •

edited

Loading

plmrry commented Apr 27, 2025 •

edited

Loading

plmrry Apr 27, 2025

styfle left a comment

pacocoursey May 1, 2025

plmrry May 1, 2025

pacocoursey May 2, 2025

plmrry May 5, 2025

		document.documentElement.removeAttribute('data-theme-test')
		document.documentElement.removeAttribute('data-example')

Add option to opt-out of automatic script insertion #353

Are you sure you want to change the base?

Add option to opt-out of automatic script insertion #353

Conversation

plmrry commented Apr 17, 2025 • edited Loading

Problem

Solution

Example

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

styfle left a comment • edited Loading

Choose a reason for hiding this comment

plmrry commented Apr 27, 2025 • edited Loading

Choose a reason for hiding this comment

styfle left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

plmrry commented Apr 17, 2025 •

edited

Loading

styfle left a comment •

edited

Loading

plmrry commented Apr 27, 2025 •

edited

Loading