tailwind-schemes weekly downloads statistics

Tailwind Color Schemes Plugin

This Tailwind CSS plugin provides a flexible way to define and use color schemes in your Tailwind CSS project. It allows you to configure global colors, scheme-specific colors, and use these colors throughout your project with optional opacity.

Tailwind CSS v4 compatibility: this plugin is built around the classic tailwind.config.js (theme.extend, plugin.withOptions) approach and works best on Tailwind CSS v3 and below. Tailwind v4 moved plugin/theme config into CSS (@theme, @plugin), but v4 still supports JS-based config for backward compatibility via the @config directive, so tailwind-schemes continues to work there too.

Installation

1. Install Tailwind CSS if you haven't already:

   npm install tailwindcss -D
   

2. Install the plugin:

   npm install tailwind-schemes -D
   

Usage

1. Configuration

   Add the plugin to your tailwind.config.js:

   // tailwind.config.js
   const { schemes, resetCSS } = require('tailwind-schemes')
   
   module.exports = {
     // ... other configurations
     plugins: [
       schemes({
         selector: 'data-theme', // Optional: "class" or any selector (default is 'data-theme' => [data-theme="dark/light/custom..."])
         prefix: 'tw-schemes', // Optional: default is 'tw-schemes'
         schemes: {
           root: {
             primary: '#3490dc',
             secondary: '#ffed4a',
             // More root colors...
           },
           light: {
             primary: '#ffffff',
             secondary: '#000000',
             // More colors for the light theme...
           },
           dark: {
             primary: '#000000',
             secondary: '#ffffff',
             // More colors for the dark theme...
           },
           customTheme: {
             primary: '#00ff00',
             secondary: '#ffff00',
             // More colors for the custom theme...
           },
         },
       }),
       resetCSS({
         html: 'text-primary', // Defined in schemes
         body: {
           padding: 0,
         },
         // More options...
       }),
     ],
   }
   

2. Using the Colors

   • Tailwind Classes

     Tailwind classes will be extended with your custom colors. You can use them directly in your HTML, including with opacity modifiers:

     <div class="text-primary bg-secondary/50">
       This text uses custom colors defined in the color schemes.
     </div>
     

   • CSS Variables

     The plugin stores each color as an r, g, b triplet in a CSS variable, so wrap it in rgb()/rgba() when using it directly in custom CSS:

     .example-class {
       color: rgb(var(--tw-schemes-primary));
       background-color: rgba(var(--tw-schemes-secondary), 0.5);
     }
     

3. Switching schemes at runtime

   With the default selector: 'data-theme', set the matching attribute on any ancestor element (commonly <html>) to switch which scheme's variables are active:

   document.documentElement.setAttribute('data-theme', 'dark')
   

   With selector: 'class', toggle a class of the same name instead (e.g. document.documentElement.classList.add('dark')).

API

schemes

The main function to configure your color schemes.

• Parameters:
  • config (optional): An object with the following properties:
    • selector (string): The CSS selector for the theme. Default is 'data-theme'.
    • prefix (string): The prefix for the CSS variables. Default is 'tw-schemes'.
    • schemes (object): An object where keys are theme names and values are color schemes.

shades

Generates a full 50-950 shade scale from a single base color.

• Parameters:

  • color (string): A hex color, with or without the leading # (e.g. '#3490dc' or '3490dc'), or an "r, g, b" string (e.g. '52, 144, 220').

• Returns: A color object with shades 50–950 generated from the base color.

colorize

Fills in DEFAULT and foreground on a color/shade object, so it can be used directly as a schemes entry.

• Parameters:

  • color (object|string): A color object (e.g. the output of shades()) or a plain string.
  • defaultKey (optional): The shade to use as DEFAULT if not already set. Default is 500.
  • foregroundKey (optional): The shade to use as foreground if not already set. Default is 950.

• Returns: The color object with DEFAULT/foreground filled in (a plain string is returned unchanged).

Combining shades + colorize to build a full scheme color from one brand color:

const { schemes, shades, colorize } = require('tailwind-schemes')

schemes({
  schemes: {
    root: {
      primary: colorize(shades('#3490dc')), // { 50: ..., ..., 950: ..., DEFAULT: '...' (500), foreground: '...' (950) }
    },
  },
})

resetCSS

A helper plugin to add global css

• Parameters:

  • options (object): define any base options (using tailwind classnames or css-properties).

• Recommended setting

   "tailwindCSS.experimental.classRegex": [
     ["resetCSS\\((([^()]*|\\([^()]*\\))*)\\)", "[\"'`]([^\"'`]*).*?[\"'`]"],
   ]
  

Contributing

See CONTRIBUTING.md for the development setup, changeset workflow, and release process.