react-theme-toggle

A headless customizable React component to toggle between light, dark, and system-preferred color schemes.

See StackBlitz Example to see the component in action

Features

• Toggles between light, dark, and system (media) themes
• Preserves theme preference across page reloads
• Reactive: theme and OS preference changes are reflected in real time
• Provides custom hooks for easy theme handling
• Compatible with React 16.8.0 and later

Installation

npm install react-theme-toggle

Usage

First, wrap your application with the ThemeProvider component:

import { ThemeProvider } from "react-theme-toggle";

const App = () => {
  return <ThemeProvider>{/* Your application components */}</ThemeProvider>;
};

Then, use the ToggleThemeButton component to add a button that toggles the theme:

import { ToggleThemeButton } from "react-theme-toggle";

const Header = () => {
  return (
    <header>
      {/* Other header content */}
      <ToggleThemeButton> Toggle Theme </ToggleThemeButton>
    </header>
  );
};

To access the current theme, use the useTheme hook:

import { useTheme } from "react-theme-toggle";

const MyComponent = () => {
  const theme = useTheme();

  return <div className={`my-component ${theme}`}>Hello, world!</div>;
};

For more advanced use cases, you can use the useThemeToggleValueState hook to get the current theme toggle value and a function to change it:

import { useThemeToggleValueState } from "react-theme-toggle";

const CustomThemeToggle = () => {
  const [themeToggleValue, setThemeToggleValue] = useThemeToggleValueState();

  return (
    <div>
      Current toggle value: {themeToggleValue}
      <button onClick={() => handleThemeToggleChange("dark")}>
        Switch to dark theme
      </button>
    </div>
  );
};

Customization

Toggle Order

To customize the order in which the theme is toggled, pass a toggleOrder prop to the ToggleThemeButton component:

import { ToggleThemeButton } from "react-theme-toggle";

const Header = () => {
  return (
    <header>
      {/* Other header content */}
      <ToggleThemeButton toggleOrder={["dark", "light", "media"]}>
        Toggle Theme
      </ToggleThemeButton>
    </header>
  );
};

The toggleOrder prop accepts an array of ToggleValue values. The default toggle order is ["light", "media", "dark"].

Styling

The ThemeToggleButton component accepts a className prop that can be used to style the button. To style different states of the button, consider utilizing the component's className along with aria-pressed attribute:

.theme-toggle-button {
  /* Default button styles */
}

.theme-toggle-button[aria-pressed="false"] {
  /* Button styles for "light" theme toggle value */
}
.theme-toggle-button[aria-pressed="mixed"] {
  /* Button styles for "media" theme toggle value */
}
.theme-toggle-button[aria-pressed="true"] {
  /* Button styles for "dark" theme toggle value */
}

API Reference

| Component | Description | Props | | ----------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | | ThemeProvider | A context provider for handling the theme state. Wrap your app with this component. | { children: React.ReactNode } | | ThemeToggleButton | A button component for toggling the theme. Switched themes from "light" to "media" to "dark" | { toggleOrder: ToggleValue[], ...React.ButtonHTMLAttributes<HTMLButtonElement>} |

| Hook | Description | Returns | | ------------------------ | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | useTheme | A hook to access the current theme. | A string representing the current theme. Possible values: "light" or "dark" ("media" toggle state will result in either "light" or "dark" value being returned, depending on the user's system preference). | | useThemeToggleValueState | A hook to get the current theme toggle value and a function to change its value. | A tuple with the following elements: 1. The current theme toggle value (one of: "light", "dark", "media"). 2. A function to change the theme toggle value. Accepts a Theme value as its argument. |

License

ISC