twr-theme

twr-theme is a React/Next.js-based theming system built on Tailwind CSS. It simplifies dynamic theming with configurable color shades, support for RGB and HEX formats, and flexible storage options (localStorage or cookies).

Installation

Install twr-theme using npm or yarn:

npm install twr-theme

or

yarn add twr-theme

Tailwind Configuration

You can automatically set up your Tailwind configuration using:

npx twr-theme

This will update your tailwind.config.js file to include necessary settings for twr-theme

Alternatively, you can manually configure it as follows:

Manual Configuration

import type { Config } from "tailwindcss";

const config: Config = {
  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: ['selector', '[data-mode="dark"]'],
  theme: {
    extend: {
      colors: {
        "primary": {
          "25": "var(--primary-25)",
          "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)",
          "950": "var(--primary-950)",
          "DEFAULT": "var(--primary-DEFAULT)",
          "light": "var(--primary-light)",
          "dark": "var(--primary-dark)"
        },
        "secondary": {
          "25": "var(--secondary-25)",
          "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)",
          "950": "var(--secondary-950)",
          "DEFAULT": "var(--secondary-DEFAULT)",
          "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: [],
};

export default config;

Manual Configuration

To generate a Tailwind configuration using RGB values, run:

npx twr-theme -rgb

Or manually update the color config like this:

const config = {
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: 'rgb(var(--primary-500) / <alpha-value>)',
          25: 'rgb(var(--primary-25) / <alpha-value>)',
          50: 'rgb(var(--primary-50) / <alpha-value>)',
          // Other shades...
        },
        secondary: {
          DEFAULT: 'rgb(var(--secondary-500) / <alpha-value>)',
          25: 'rgb(var(--secondary-25) / <alpha-value>)',
          // Other shades...
        }
      }
    }
  }
}

Note

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

Usage

ThemeProvider

Wrap your application with the ThemeProvider and define the configuration.

import { ThemeProvider } from 'twr-theme';

<ThemeProvider
  config={{
    shades: ["25", "50", "100", "200", "300", "400", "500", "600", "700", "800", "900", '950', "dark", "light"],
    colorType: "hex", // or "rgb"
    storage: "cookie", // or "localStorage"
  }}
>
  {children}
</ThemeProvider>

Props

• shades: Defines the shades you want to use. These must match the shades in your Tailwind config.
• colorType: Choose either "hex" or "rgb" for color values.
• storage: Define the storage mechanism for the theme, either "localStorage" or "cookie" (default is "localStorage").

ColorSchemeScript

For Next.js (or server-side rendering), use ColorSchemeScript to prevent flashing issues when switching themes. This component manages the initial theme state on the server.

<ColorSchemeScript 
  storage="cookie" 
  themeModeKey="theme-mode" 
  themeLocalStorageKey="trio-theme" 
  colorType="hex"
/>

ColorSchemeScript Default Values

The ColorSchemeScript component plays a crucial role in ensuring the theme's initial state is correctly loaded in server-side rendering environments like Next.js. By default, it uses two important key names for managing the theme's mode and storage in localStorage or cookies:

• themeModeKey: This key stores the current mode of the theme (e.g., "dark", "light", or "system"). The default value is "theme-mode".
• themeLocalStorageKey: This key stores the actual theme configuration (colors, shades, etc.). The default value for this is "trio-theme".

Setting a Default Theme Based on colorType

The ThemeProvider and ColorSchemeScript also allow you to define a default theme, which will be loaded when the app is first run or if no theme is found in storage. This default theme can vary based on the colorType (either rgb or hex).

Example: RGB Default Theme

If the colorType is set to "rgb", you can define a default theme using RGB values for the color shades like so:

<ThemeProvider
  config={{
    colorType: "rgb", // Define the color type
    shades: ["25", "50", "100", "200", "300", "400", "500", "600", "700", "800", "900", '950', "dark", "light"],
  }}
>
  <ColorSchemeScript
    colorType="rgb"
    defaultTheme={{
      name: "default",
      mode: "system",
      shades: [
        {
          name: "primary",
          color: "0 128 128",
          shade: {
            "25": "245 252 252",
            "50": "237 250 250",
            "100": "218 242 242",
            "200": "168 224 224",
            "300": "122 204 204",
            "400": "50 166 166",
            "500": "0 128 128",
            "600": "0 109 115",
            "700": "0 82 94",
            "800": "0 61 77",
            "900": "0 40 56",
            "950": "0 23 36",
            "light": "245 252 252",
            "dark": "0 7 13"
          }
        },
        {
          name: "secondary",
          color: "15 111 255",
          shade: {
            "25": "247 253 255",
            "50": "242 251 255",
            "100": "232 247 255",
            "200": "196 233 255",
            "300": "158 215 255",
            "400": "87 168 255",
            "500": "15 111 255",
            "600": "11 95 230",
            "700": "8 72 191",
            "800": "6 53 153",
            "900": "3 35 115",
            "950": "1 20 74",
            "light": "247 253 255",
            "dark": "1 20 74"
          }
        }
      ]
    }}
  />
  {children}
</ThemeProvider>

Conclusion

twr-theme offers a flexible, easy-to-implement theming system for React and Next.js apps, integrated with Tailwind CSS. For detailed configuration and usage, explore the package documentation or examples provided.

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!