@adrienlcp/theme-preference
Un thème clair, sombre ou système sans flash au chargement, une barre d’outils du navigateur qui suit le choix, et des mixins Sass pour une valeur par thème que light-dark() ne sait pas porter
Fonctionne avec
- TypeScript
- CSS
- Reactpeer facultatif
- Sasspeer facultatif
- Vitepeer facultatif
Installation
pnpm add @adrienlcp/theme-preferenceExports
Groupés par la section de la documentation qui les explique. Une ligne mène à sa section.
The markup2 exports
@adrienlcp/theme-preference/ color-scheme.css @adrienlcp/Fichiertheme-preference/ color-scheme.css darkA valuelight-dark()cannot carry — a percentage, a length, a shadow's geometry, an image — set per theme with the same precedence ascolor-scheme.css: the explicit choice stamped indata-themebeats the system preference.@adrienlcp/Sasstheme-preference/ scheme
The store1 export
Before the first paint1 export
React1 export
Documentés dans le code seulement5 exports
applyThemePreferenceStampsdata-themeon<html>for an explicit scheme, removes it for'system'so the stylesheet'sprefers-color-schemerules answer, and points everytheme-colortag at the same palette.@adrienlcp/Fonctiontheme-preference THEME_PREFERENCES@adrienlcp/Constantetheme-preference ThemePreferenceWhat the visitor chose.@adrienlcp/Typetheme-preference isThemePreference@adrienlcp/Fonctiontheme-preference ThemePreferenceStore@adrienlcp/Typetheme-preference
Documentation
Le README et les documents à côté, tels qu’écrits dans le dépôt.
PrésentationREADME.md
Light, dark or system theme: no flash of the wrong palette on load, and a
browser toolbar that follows the choice. No third-party dependency: storage goes
through @adrienlcp/safe-storage.
The detail most theme switchers miss: a phone paints its address bar from
<meta name="theme-color">. Those tags ship scoped to
prefers-color-scheme, so a visitor who picks dark on a light system keeps a
light toolbar over a dark page. This package switches each tag's media
between all, not all and the media query, both before the first paint and
live.
pnpm add @adrienlcp/theme-preferenceThe markupREADME.md
One theme-color tag per scheme, each saying which scheme it colours:
<meta name="theme-color" data-scheme="light" content="#ffffff" media="(prefers-color-scheme: light)" />
<meta name="theme-color" data-scheme="dark" content="#101010" media="(prefers-color-scheme: dark)" />The stylesheet follows the system by default and yields to data-theme. The
package ships it: import @adrienlcp/theme-preference/color-scheme.css once
(or @use it from Sass), and write every colour token as
light-dark(<light>, <dark>):
:root { color-scheme: light dark; }
:root[data-theme="light"] { color-scheme: light; }
:root[data-theme="dark"] { color-scheme: dark; }The file is unlayered, so it wins over any color-scheme a layered stylesheet
sets.
A value light-dark() cannot carry — a percentage, a length, a shadow's
geometry — goes through the scheme Sass mixins, which follow the same
precedence: the system preference, unless data-theme says otherwise.
@use '@adrienlcp/theme-preference/scheme'
@layer tokens
@include scheme.dark
--tint-strength: 38%The storeREADME.md
// theme.ts
import { createThemePreferenceStore } from '@adrienlcp/theme-preference'
export const themeStore = createThemePreferenceStore({ storageKey: 'app:theme' })getPreference(), setPreference(preference) and subscribe(listener).
setPreference persists the choice, stamps the document and notifies every
subscriber. A preference is 'system' | 'light' | 'dark'; 'system' is stored
as no entry at all. Storage that throws, as in a Safari private window, reads as
'system' and keeps a new choice for the current page view.
Before the first paintREADME.md
The pre-paint script must run in <head>, after the theme-color tags. With
Vite, the plugin appends it to every page, reading the key from the store:
// vite.config.ts
import { themePreferencePlugin } from '@adrienlcp/theme-preference/vite'
import { themeStore } from './src/theme'
export default defineConfig({ plugins: [themePreferencePlugin(themeStore)] })Without Vite, inline themeStore.prePaintScript yourself.
ReactREADME.md
import { useThemePreference } from '@adrienlcp/theme-preference/react'
const ThemeSwitch = () => {
const { preference, setPreference } = useThemePreference(themeStore)
// …
}Every component using the hook re-renders on a change. A server render reads
'system'.