react-theme-lib

v1.0.3

Published

4 years ago

Simple react theming library with prefers-color-scheme media support

0High
0Medium
0Low

nikitakhodakovsky

react theme theming prefers-color-scheme dark dark-mode css-variables hook hooks

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

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

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Table of contents