Reliable dark theme toggling logic with no theme flicker and comprehensive testing.
Theme toggling should not be entirely controlled by JavaScript. When the theme is set to "system," it should automatically match the prefers-color-scheme media query.
Theme Flickering
If the default page theme is light and has already rendered, when the script identifies the need for a dark theme and switches styles, users can noticeably perceive the flicker, diminishing the user experience.
pnpm i dark-toggleThis library can be used vanilla or with React.
import { createDarkToggle } from 'dark-toggle'
const darkToggle = createDarkToggle({
key: 'theme',
})
darkToggle.subscribe((dark, theme) => {
if (dark) {
document.documentElement.classList.add('dark')
} else {
document.documentElement.classList.remove('dark')
}
document.documentElement.setAttribute('data-theme', theme ?? '')
})
const btn = document.querySelector('button')
btn.onclick = darkToggle.toggleThe following describes the API based on the interface provided:
const createDarkToggle = (params: Params): Return
export interface Params {
storage?: Storage; // Specifies the storage used, default SessionStorage
key: string;
}
export interface Return {
// Indicates if the dark theme is active
isDark: boolean;
// Current theme
theme: Theme | null;
// Function to set the theme
setTheme: (theme: Theme) => void;
// Function to toggle light/dark themes
toggle: VoidFunction;
// Subscribe to changes, returns unsubscribe function
subscribe: (cb: SubscribeFunction) => () => void;
}Here's an example of usage in a Next.js application:
// layout.ts
import { DarkToggleScript, DarkToggleProvider } from 'dark-toggle/react';
export default function RootLayout({
children,
}: Readonly<{
children: React.ReactNode;
}>) {
return (
<html suppressHydrationWarning lang="en">
<body>
<DarkToggleProvider>{children}</DarkToggleProvider>
<DarkToggleScript />
</body>
</html>
);
}Component Usage
import { useDarkToggle } from 'dark-toggle/react'
export default function Toggle() {
const { isDark, theme, toggle } = useDarkToggle()
return (
<main>
<p>isDark: {`${isDark}`}</p>
<p>theme: {theme}</p>
<button onClick={toggle}>Toggle</button>
</main>
)
}<DarkToggleScript/> Initialization script.
<DarkToggleProvider/> Provider.
useDarkToggle(): Return
useDarkToggle returns the same values as createDarkToggle used vanilla. The only difference is that isDark and theme are states, ensuring that hook values change when properties change.
The DarkToggleScript injects the script into the page at a different timing than React, avoiding theme flickering.
It communicates with React through the window.darkToggle object. It is recommended to use useDarkToggle; however, you can directly access it in your code if needed.
Contributions are welcome.