Gathering detailed insights and metrics for tw-colors
Gathering detailed insights and metrics for tw-colors
Tailwind plugin to easily add multiple color themes to your projects.
Installations
npm install tw-colorsDeveloper Guide
BETA
Typescript
Yes
Module System
CommonJS
Node Version
20.11.1
NPM Version
10.2.4
Score
99.1
Supply Chain
98.7
Quality
78.7
Maintenance
100
Vulnerability
99.6
License
Releases
Unable to fetch releases
Languages
4
TypeScript
HTML
JavaScript
CSS
TypeScript (42.15%)
HTML (41.38%)
JavaScript (16.08%)
CSS (0.4%)
Developer
L-Blondy
Download Statistics
Total Downloads
2,609,293
Last Day
2,021
Last Week
46,192
Last Month
201,252
Last Year
1,951,473
GitHub Statistics
MIT License
506 Stars
198 Commits
16 Forks
4 Watchers
1 Branches
4 Contributors
Updated on Jun 29, 2025
Bundle Size
28.60 kB
Minified
10.03 kB
Minified + Gzipped
Maintainers
1
Package Meta Information
Latest Version
3.3.2
Package Id
tw-colors@3.3.2
Unpacked Size
100.71 kB
Size
18.98 kB
File Count
22
NPM Version
10.2.4
Node Version
20.11.1
Published on
Sep 04, 2024
Total Downloads
Cumulative downloads
Total Downloads
2,609,293
Last Day
0.2%
2,021
Compared to previous day
Last Week
-4.3%
46,192
Compared to previous week
Last Month
8.3%
201,252
Compared to previous month
Last Year
214.8%
1,951,473
Compared to previous year
Weekly Downloads
Monthly Downloads
Yearly Downloads
Dependencies
3
Peer Dependencies
1
tw-colors
Introducing the ultimate game-changer for your Tailwind app! Say goodbye to cluttered dark variants and messy CSS variables. With this tailwind plugin, switching between color themes is as effortless as changing one className.
Highlights
- 🚀 Scalable, add as many themes and colors as you want. There is no limit on the number of themes and color you can use
- 💫 Flexible, don't limit yourself to colors, with the built-in variants you can theme any css property
- ✨ Easy to adopt, no need to change your markup, it just works!
- 🤩 Nested themes are supported for complex use cases
- 🎯 Full Tailwind CSS Intellisense support 🔥🔥🔥
Changelog
See the full changelog here
Usage
1npm i -D tw-colors
Take an existing tailwind config and move the colors in the createThemes plugin, giving it a name (e.g. light).
tailwind.config.js
1+ const { createThemes } = require('tw-colors'); 2 3 module.exports = { 4 content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'], 5 theme: { 6 extends: { 7- colors: { 8- 'primary': 'steelblue', 9- 'secondary': 'darkblue', 10- 'brand': '#F3F3F3', 11- // ...other colors 12- } 13 }, 14 }, 15 plugins: [ 16+ createThemes({ 17+ light: { 18+ 'primary': 'steelblue', 19+ 'secondary': 'darkblue', 20+ 'brand': '#F3F3F3', 21+ // ...other colors 22+ } 23+ }) 24 ], 25 }; 26
💡 tip: you can use any color name as you usually do, not just the ones from the example. The same goes for the theme names.
Apply class='light' or data-theme='light' anywhere in your app (the html or the body tag is a good spot for it)
See the options to customize the className
1- <html> 2+ <html class='light'> 3 ... 4 <div class='bg-brand'> 5 <h1 class='text-primary'>...</h1> 6 <p class='text-secondary'>...</p> 7 </div> 8 ... 9 </html>
That's it, your site has a light theme!
Adding more themes
tailwind.config.js
1 const { createThemes } = require('tw-colors'); 2 3 module.exports = { 4 content: ['./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}'], 5 plugins: [ 6 createThemes({ 7 light: { 8 'primary': 'steelblue', 9 'secondary': 'darkblue', 10 'brand': '#F3F3F3', 11 }, 12+ dark: { 13+ 'primary': 'turquoise', 14+ 'secondary': 'tomato', 15+ 'brand': '#4A4A4A', 16+ }, 17+ forest: { 18+ 'primary': '#2A9D8F', 19+ 'secondary': '#E9C46A', 20+ 'brand': '#264653', 21+ }, 22+ winter: { 23+ 'primary': 'hsl(45 39% 69%)', 24+ 'secondary': 'rgb(120 210 50)', 25+ 'brand': 'hsl(54 93% 96%)', 26+ }, 27 }) 28 ], 29 };
You now have a light, a dark and a forest theme!
Switching themes
Simply switch the class or the data-theme attribute
1- <html class='light'> 2+ <html class='dark'> 3 ... 4 </html>
Variants
Based on the current theme, specific styles can be applied using variants.
Note: In the following example the variants would have no effect with data-theme='light'
1 <!-- Use "serif" font for the dark theme only --> 2 <div data-theme='dark' class='font-sans dark:font-serif'> 3 ... 4 <div>Serif font here</div> 5 6 <!-- this button is rounded when the theme is `dark` --> 7 <button class='dark:rounded'>Click Me</button> 8 </div>
See the options to customize the variant name
Caveat: group-{modifier}
Always use the group variant before the theme variant.1 <html class='theme-dark'> 2 ... 3 <div class='group'> 4 <div class='theme-dark:group-hover:bg-red-500'> 5 ❌ the group variant does not work 6 </div> 7 <div class='group-hover:theme-dark:bg-red-500'> 8 ✅ the group variant works properly 9 </div> 10 </div> 11 </html>
Nested themes
With data-theme
Just nest the themes...
1 <html data-theme='dark'> 2 ... 3 <div data-theme='winter'> 4 ... 5 </div> 6 7 <div data-theme='forest'> 8 ... 9 </div> 10 </html>
With class
For variants to work properly in nested themes, an empty data-theme attribute must be added alongside the nested theme class
1 <html class='dark'> 2 ... 3 <div data-theme class='winter'> 4 ... 5 </div> 6 7 <div data-theme class='forest'> 8 ... 9 </div> 10 </html>
Caveats:
Do not set opacity in the color definition
When using nested themes, it is better not to provide a base opacity in your color definitions.With this setup the 0.8 opacity defined on the primary color of the "parent" theme will be inherited by the "child" theme's primary color.
1createThemes({ 2 parent: { 3 'primary': 'hsl(50 50% 50% / 0.8)', // don't do this, the default opacity will propagate to the child theme 4 'secondary': 'darkblue', 5 }, 6 child: { 7 'primary': 'turquoise', 8 'secondary': 'tomato', 9 }, 10})
1<html data-theme='parent'> 2 3 <div data-theme='child'> 4 <!-- The primary color has an unexpected 0.8 opacity --> 5 <button class='bg-primary'>Click me</button> 6 7 ... 8 </div> 9</html>
Inherited properties
Inherited properties (e.g. "font-family") are inherited by all descendants, including nested themes. In order to stop the propagation the base styles should be re-declared on nested themes
❌ Unexpected behavior
1 <html class='theme-dark font-sans theme-dark:font-serif'> 2 ... 3 <div> 4 ✅ Serif is active 5 </div> 6 7 <div class="theme-light"> 8 ❌ Serif is still active, it got inherited from the parent theme 9 </div> 10 </html>
✅ Works as expected
1 <html class='theme-dark font-sans theme-dark:font-serif'> 2 ... 3 <div> 4 ✅ Serif is active 5 </div> 6 7 <div class="theme-light font-sans theme-dark:font-serif"> 8 ✅ Sans is active 9 </div> 10 </html>
CSS color-scheme
createThemes also accepts a function that exposes the light and dark functions.
To apply the color-scheme CSS property, simply wrap a theme with light or dark."
See the MDN docs for more details on this feature.
tailwind.config.js
1createThemes(({ light, dark }) => ({ 2 'winter': light({ 3 'primary': 'steelblue', 4 'base': 'darkblue', 5 'surface': '#F3F3F3', 6 }), 7 'forest': dark({ 8 'primary': 'turquoise', 9 'base': 'tomato', 10 'surface': '#4A4A4A', 11 }), 12}))
CSS Variables
tw-colors creates CSS variables using the format --twc-[color name] by default, they contain HSL values.
For example, with the following configuration, the variables --twc-primary, --twc-base, --twc-surface will be created.
tailwind.config.js
1 module.exports = { 2 // ...your tailwind config 3 plugins: [ 4 createThemes({ 5 'winter': { 6 'primary': 'steelblue', 7 'base': 'darkblue', 8 'surface': '#F3F3F3', 9 }, 10 'forest': { 11 'primary': 'turquoise', 12 'base': 'tomato', 13 'surface': '#4A4A4A', 14 }, 15 }) 16 ], 17 };
Example usage:
1.my-class { 2 color: hsl(var(--twc-primary)); 3 background: hsl(var(--twc-primary) / 0.5); 4}
See the options to customize the css variables
Options
The options can be passed as the second argument to the plugin
1createThemes({ 2 // your colors config here... 3}, { 4 produceCssVariable: (colorName) => `--twc-${colorName}`, 5 produceThemeClass: (themeName) => `theme-${themeName}` 6 produceThemeVariant: (themeName) => `theme-${themeName}` 7 defaultTheme: 'light' 8 strict: false 9})
defaultTheme
The default theme to use, think of it as a fallback theme when no theme is declared.
Example: simple default theme
1createThemes({ 2 'winter': { 3 'primary': 'steelblue', 4 }, 5 'halloween': { 6 'primary': 'crimson', 7 }, 8}, { 9 defaultTheme: 'winter' // 'winter' | 'halloween' 10})
The default theme can also be chosen according to the user light or dark preference (see MDN prefers-color-scheme)
Example: adapting to user preference
1createThemes({ 2 'winter': { 3 'primary': 'steelblue', 4 }, 5 'halloween': { 6 'primary': 'crimson', 7 }, 8}, { 9 defaultTheme: { 10 /** 11 * when `@media (prefers-color-scheme: light)` is matched, 12 * the default theme is the "winter" theme 13 */ 14 light: 'winter', 15 /** 16 * when `@media (prefers-color-scheme: dark)` is matched, 17 * the default theme is the "halloween" theme 18 */ 19 dark: 'halloween', 20 } 21})
strict
default: false
If false invalid colors are ignored.
If true invalid colors produce an error.
Example
1createThemes({
2 'christmas': {
3 // invalid color
4 'primary': 'redish',
5 },
6 'darkula': {
7 'primary': 'crimson',
8 },
9}, {
10 // an error will be thrown
11 strict: true
12})produceCssVariable
default: (colorName) => `--twc-${colorName}`
Customize the css variables generated by the plugin.
With the below configuration, the following variables will be created:
--a-primary-z(instead of twc-primary)--a-secondary-z(instead of twc-secondary)--a-base-z(instead of twc-base)
1createThemes({ 2 'light': { 3 'primary': 'steelblue', 4 'secondary': 'darkblue', 5 'base': '#F3F3F3', 6 }, 7 'dark': { 8 'primary': 'turquoise', 9 'secondary': 'tomato', 10 'base': '#4A4A4A', 11 }, 12}, { 13 produceCssVariable: (colorName) => `--a-${colorName}-z` 14})
produceThemeClass
default: (themeName) => themeName
Customize the classNames of the themes and variants
With the below configuration, the following theme classNames and variants will be created:
theme-light(instead of light)theme-dark(instead of dark)
1createThemes({ 2 'light': { 3 'primary': 'steelblue', 4 'secondary': 'darkblue', 5 'base': '#F3F3F3', 6 }, 7 'dark': { 8 'primary': 'turquoise', 9 'secondary': 'tomato', 10 'base': '#4A4A4A', 11 }, 12}, { 13 produceThemeClass: (themeName) => `theme-${themeName}` 14})
1<html class='theme-dark'> 2 ... 3 <button class='theme-dark:rounded'> 4 Click Me 5 </button> 6 ... 7</html>
produceThemeVariant
default: same as produceThemeClass
Customize the variants
With the below configuration, the following variants will be created:
theme-light(instead of light)theme-dark(instead of dark)
1createThemes({ 2 'light': { 3 'primary': 'steelblue', 4 'secondary': 'darkblue', 5 'base': '#F3F3F3', 6 }, 7 'dark': { 8 'primary': 'turquoise', 9 'secondary': 'tomato', 10 'base': '#4A4A4A', 11 }, 12}, { 13 produceThemeVariant: (themeName) => `theme-${themeName}` 14})
1<html data-theme='dark'> 2 ... 3 <button class='theme-dark:rounded'> 4 Click Me 5 </button> 6 ... 7</html>
From the same Author
up-fetch: Tiny 1kb configuration tool for the fetch API with sensible default
Please share
No vulnerabilities found.
No security vulnerabilities found.