react-theme-toggle v0.1.0

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

License

ISC