Package Exports

react-theme-lib
react-theme-lib/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (react-theme-lib) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

It is a simple library for working with themes in React with support of prefers-color-scheme media query

Installation
Usage
Theme Priority
Storing theme on the server
API

Instalation

npm i react-theme-lib

⚠️ To use this package, you must have React version 16.8.0 or higher installed

Usage

First, you must wrap your application in <ThemeProvider /> by passing an instance of ThemeManager

import { ThemeManager, ThemeProvider } from 'react-theme-lib'

const manager = new ThemeManager({
    htmlElement: document.getElementById('body') as HTMLElement
})

root.render(
    <ThemeProvider manager={manager}>
        <App />
    </ThemeProvider>
)

Then you can use useTheme hook inside your components

import { useTheme } from 'react-theme-lib'

function App() {
    const { theme, toggleTheme } = useTheme()

    return (
        <Fragment>
            <div>{theme}</div>
            <button onClick={toggleTheme}>Toggle Theme</button>
        </Fragment>
    )
}

A class corresponding to the current theme will be added to the passed element

For example:

<body class="dark">
    ...
</body>

So you can easily make something like this

body.light {
    --background: #fff;
}

body.dark {
    --background: #333;
}

.element {
    background-color: var(--background);
}

Theme Priority

This library provides the term "Theme Priority", which must be understood in order to use the library. It is a mechanism for determining the theme on loading

Which can be represented by the following expression:

userTheme > computedTheme

userTheme

This theme is explicitly set by the user by calling setTheme of toggleTheme. This theme is saved in the localStorage and will be read the next time the application is loaded

previousUserTheme > themeFromLocalStorage

previousUserTheme parameter passed to ThemeManager has priority over the theme stored in localStorage. Used for Storing theme on the server
themeFromLocalStorage - Theme previously explicitly specified by the user and saved in localStorage. Automatically retrieved, validated and set in ThemeManager constructor

computedTheme

This is theme that is used if the user has not yet explicitly set a theme. Defined from the following parameters in the ThemeManager constructor:

superiorTheme > prefferedThemeMedia > defaultTheme

superiorTheme - The theme that will be installed when the application first starts up despite on prefers-colour-scheme media and defaultTheme. Should only be used as a last resort, as an application with a good UX should rely on prefers-color-scheme media
prefferedThemeMedia - Calculated within the ThemeManager constructor as a result of running prefers-color-scheme media. Takes precedence over the default theme
defaultTheme - Theme that is passed as parameter to ThemeManager and has the lowest priority and will be installed if prefers-color-scheme media fails. The default is 'light'.

Storing theme on the server

If for some reason you want to store a user-selected theme on the server or elsewhere, you can use previousUserTheme and onUserSetTheme

const previousUserTheme = fetchTheme()
const onUserSetTheme = (theme: Theme) => sendThemeToTheServer()

const manager = new ThemeManager({
    previousUserTheme,
    onUserSetTheme
})

const ui = (
    <ThemeProvider manager={manager}>
        <App />
    </ThemeProvider>
)

API

Basic types

type Theme = 'light' | 'dark'

type Subscriber = (t: Theme) => any

type UnsubscribeFunction = () => void

ThemeManager

The main thing about the library. Accepts optional ThemeManagerOptions

const manager = new ThemeManger()

Provides the following methods:

getTheme(): Theme

setTheme(theme: Theme): void

subscribe(subscriber: Subscriber): UnsubscribeFunction

listen(): UnsubscribeFunction;

These methods are used internally by the library. The only thing you have to do with ThemeManager is to pass it to <ThemeProvider/>

ThemeManagerOptions

interface ThemeManagerOptions {
    previousUserTheme?: Theme
    superiorTheme?: Theme
    defaultTheme?: Theme
    keepInLocalStorage?: boolean
    localStorageKey?: string
    htmlElement?: HTMLElement
    onChange?: Subscriber
    onUserSetTheme?: Subscriber
    disablePrefersColorScheme?: boolean
    customLightClass?: string
    customDarkClass?: string
}

Property	Description
previousUserTheme	Described in Storing theme on the server
superiorTheme	Described in Theme Priority section
defaultTheme	Described in Theme Priority section
keepInLocalStorage	Whether to save theme selected by the user to the localStorage. By default - true
localStorageKey	The key under which the theme selected by the user will be stored in the localStorage. By default = 'theme'
htmlElement	Element to which a class will be added, depending on the theme
onChange	Listener, which will be called when the theme changes
onUserSetTheme	Described in Storing theme on the server
disablePrefersColorScheme	The flag that specifies whether ThemeManager will consider prefers-color-scheme when calculating computedTheme
customLightClass	The class that will be added when theme === 'light' to the passed component. If not specified, 'light' will be added by default
customDarkClass	The class that will be added when theme === 'dark' to the passed component. If not specified, 'dark' will be added by default

ThemeProvider

React context provider that takes an instance of ThemeManager and makes it available for useThemeManager and useTheme hooks. Also responsible for setting eventListeners on prefers-color-scheme media.

const manager = new ThemeManager()

const ui = (
    <ThemeProvider manager={manager}>
        <App />
    </ThemeProvider>
)

If you haven't explicitly set UserTheme yet, you can change the theme in your operating system, and it will automatically change in your application because of eventListeners on prefers-color-scheme media

useTheme

Hook, which provides access to the core React API of this library.

interface UseThemeResult {
    theme: Theme
    isDark: boolean
    isLight: boolean
    setTheme: (theme: Theme) => void
    toggleTheme: () => void
}

function useTheme(): UseThemeResult

Property	Description
theme	Current theme
isDark	true if theme === 'dark'
isLight	true if theme === 'light'
setTheme	The function that sets the theme
toggleTheme	A function that switches the current theme to the opposite one

useThemeManager

Hook, which returns the current instance of ThemeManager

function useThemeManager(): ThemeManager

react-theme-lib