twr-theme Documentation

Overview

twr-theme is a React-based package that allows you to implement theming in your application using Tailwind CSS. It provides components and hooks for easy theme management, ensuring a seamless integration with Tailwind's utility-first CSS framework.

Installation

Install twr-theme using npm or yarn:

npm install twr-theme

or

yarn add twr-theme

To generate or update your Tailwind config easily, use the following command:

npx twr-theme

Tailwind CSS Configuration

To integrate twr-theme with Tailwind CSS, update your tailwind.config.js as follows:

module.exports = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/twr-theme/**/*.{js,ts,jsx,tsx,mdx}", // Include twr-theme from your node_modules
  ],
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "var(--primary)",
          50: "var(--primary-50)",
          100: "var(--primary-100)",
          200: "var(--primary-200)",
          300: "var(--primary-300)",
          400: "var(--primary-400)",
          500: "var(--primary-500)",
          600: "var(--primary-600)",
          700: "var(--primary-700)",
          800: "var(--primary-800)",
          900: "var(--primary-900)",
          light: "var(--primary-light)",
          dark: "var(--primary-dark)",
        },
        secondary: {
          DEFAULT: "var(--secondary)",
          50: "var(--secondary-50)",
          100: "var(--secondary-100)",
          200: "var(--secondary-200)",
          300: "var(--secondary-300)",
          400: "var(--secondary-400)",
          500: "var(--secondary-500)",
          600: "var(--secondary-600)",
          700: "var(--secondary-700)",
          800: "var(--secondary-800)",
          900: "var(--secondary-900)",
          light: "var(--secondary-light)",
          dark: "var(--secondary-dark)",
        },
      },
      backgroundImage: {
        "gradient-radial": "radial-gradient(var(--tw-gradient-stops))",
        "conic-gradient": "conic-gradient(var(--tw-gradient-stops))",
      },
    },
  },
  plugins: [],
};

Note

Ensure that primary and secondary shades are not changed directly in the Tailwind config to avoid theme malfunction.

Components

ThemeProvider

The ThemeProvider component wraps your entire application to provide theme context.

Props

• children: React.ReactNode - The content to be wrapped by the provider.
• defaultTheme: { name: string; mode: string; colorVars: { primary: string; secondary: string; }; } - The default theme settings.
• themeLoader: React.ReactNode - A loader component to be displayed while the theme is loading.

Example

import { ThemeProvider } from "twr-theme";

const defaultTheme = {
  name: "light",
  mode: "light",
  colorVars: {
    primary: "#3490dc",
    secondary: "#ffed4a",
  },
};

function Main({ children }) {
  return (
    <ThemeProvider defaultTheme={defaultTheme}>
      {children}
      {/* Your app components */}
    </ThemeProvider>
  );
}

ThemeProvider

The ThemeController component provides UI controls to manage the theme. If you want to hassle free theme controll just import ThemeController inside any of your app component and use it.

Example

import { ThemeController } from "twr-theme";

function App() {
  return (
    <div>
      <ThemeController />
      {/* Your app components */}
    </div>
  );
}

Hooks

Do you want to change the theme in your own way? Then use our interactive hooks.😉

useTheme

The useTheme hook provides various methods and properties to manage the theme.

Returns

• theme: Current theme object.
• themeList: List of available themes.
• setTheme: Function to set a specific theme.
• addTheme: Function to add a new theme.
• removeTheme: Function to remove a theme.
• toggleTheme: Function to toggle between themes.
• toggleDarkMode: Function to toggle dark mode.
• changeTheme: Function to change the theme properties.

Returns

• toggleDarkMode(mode: "dark" | "light" | "system"): Toggle the dark mode setting.
• toggleTheme(themeItem: { name: string; mode: string; colorVars: { primary: string; secondary: string; } }): Toggle between themes.
• changeTheme(theme: { name: string; colorVars: { primary: string; secondary: string; } }): Change theme properties.
• removeTheme(themeName: string): Remove a theme by name.
• addTheme(theme: { name: string; colorVars: { primary: string; secondary: string; } }): Add a new theme.

Example

import { useTheme } from "twr-theme";

function MyComponent() {
  const {
    theme,
    setTheme,
    toggleDarkMode,
    toggleTheme,
    changeTheme,
    removeTheme,
    addTheme,
  } = useTheme();

  const newTheme = {
    name: "new-theme",
    mode: "light",
    colorVars: { primary: "#123456", secondary: "#654321" },
  };

  const updatedTheme = {
    name: "updated-theme",
    colorVars: { primary: "#abcdef", secondary: "#fedcba" },
  };

  return (
    <div>
      <p>Current Theme: {theme.name}</p>
      <button onClick={() => setTheme("dark")}>Set Dark Theme</button>
      <button onClick={() => toggleDarkMode("dark")}>Toggle Dark Mode</button>
      <button onClick={() => toggleTheme(newTheme)}>Toggle Theme</button>
      <button onClick={() => changeTheme(updatedTheme)}>Change Theme</button>
      <button onClick={() => removeTheme("new-theme")}>Remove Theme</button>
      <button onClick={() => addTheme(newTheme)}>Add Theme</button>
    </div>
  );
}

useTWVariableColor

The useTWVariableColor hook allows you to access and update Tailwind CSS variables dynamically. This hook is essential for managing theme colors and adding new variables to your theme.

Usage

To use useTWVariableColor, you need to provide the variable name as an argument. The hook returns the current value of the variable and a function to update the variable.

const [colorValue, setColorValue] = useTWVariableColor({
  variable: "variable-name",
});

Parameters

• variable: A string representing the name of the Tailwind CSS variable. This variable should also be defined in the Tailwind config with shades if necessary.

Returns

• colorValue: The current value of the specified variable.
• setColorValue: A function that takes a color code to update the variable.

Example

Below is an example of how to use useTWVariableColor to manage the variable color in your theme.

If you want to add a new variable to your theme, follow these steps:

Step 1: Update Tailwind Config

Add the new variable in your tailwind.config.js:

module.exports = {
  content: [
    "./src/pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/components/**/*.{js,ts,jsx,tsx,mdx}",
    "./src/app/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/twr-theme/**/*.{js,ts,jsx,tsx,mdx}", // Include twr-theme
  ],
  darkMode: "class",
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "var(--primary)",
          50: "var(--primary-50)",
          // other shades...
        },
        custom: {
          // New variable
          DEFAULT: "var(--custom)",
          50: "var(--custom-50)",
          100: "var(--custom-100)",
          200: "var(--custom-200)",
          300: "var(--custom-300)",
          400: "var(--custom-400)",
          500: "var(--custom-500)",
          600: "var(--custom-600)",
          700: "var(--custom-700)",
          800: "var(--custom-800)",
          900: "var(--custom-900)",
          light: "var(--custom-light)",
          dark: "var(--custom-dark)",
        },
      },
    },
  },
  plugins: [],
};

Step 2: Using useTWVariableColor for the New Variable

import { useTWVariableColor } from "twr-theme";

function MyComponent() {
  const [custom, setCustom] = useTWVariableColor({ variable: "custom" });

  return (
    <div>
      <p>Custom Color: {custom}</p>
      <button onClick={() => setCustom("#abcdef")}>Change Custom Color</button>
    </div>
  );
}

By using useTWVariableColor, you can dynamically control all theme variables, ensuring a flexible and scalable theming solution for your application.

Conclusion

The twr-theme package provides a robust and flexible solution for implementing theming in your React applications using Tailwind CSS. By leveraging components like ThemeProvider, ThemeController, and ColorPalette, along with hooks such as useTWVariableColor and useTheme, you can easily manage and customize your application's theme.

For any questions or further assistance, feel free to reach out or refer to the source code for more examples and usage patterns.

This conclusion ties together the main points of the documentation and provides a clear ending. Let me know if there's anything else you'd like to include!