react-theme-lib
TypeScript icon, indicating that this package has built-in type declarations

1.0.3 • Public • Published

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


Table of contents


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

  1. previousUserTheme parameter passed to ThemeManager has priority over the theme stored in localStorage. Used for Storing theme on the server
  2. 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

  1. 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

  2. prefferedThemeMedia - Calculated within the ThemeManager constructor as a result of running prefers-color-scheme media. Takes precedence over the default theme

  3. 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

Package Sidebar

Install

npm i react-theme-lib

Weekly Downloads

4

Version

1.0.3

License

MIT

Unpacked Size

15.9 kB

Total Files

12

Last publish

Collaborators

  • nikitakhodakovsky