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:

2. Install the plugin:

Usage

1. Configuration

Add the plugin to your tailwind.config.js:

1. 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:

• 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:

1. Switching schemes at runtime

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

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:

resetCSS

A helper plugin to add global css

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

Contributing

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