Skip to content

Latest commit

 

History

History
194 lines (143 loc) · 5.83 KB

readme.md

File metadata and controls

194 lines (143 loc) · 5.83 KB
Raw

tailwind-dark-aware

Tailwind CSS plugin to generate shorthands for light mode and dark mode colour classes.

Branch status Codecov

Demo app

Deployment: https://tailwind-dark-aware.vercel.app
Source: https://github.com/joulev/tailwind-dark-aware/tree/main/demo

Installation

npm install -D tailwind-dark-aware

Then add the plugin in your tailwind.config.js file:

module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require("tailwind-dark-aware"),
    // or if you want to call with options:
    require("tailwind-dark-aware")({
      // your options here
    }),
    // ...
  ],
};

Basic usage

This plugin generates classes such as text-daw-red-700 and border-x-daw-emerald-200 that sets the colour dynamically in light mode and dark mode. The light mode version is the one you specify, while the dark mode is the opposite one in the same palette. Essentially, text-daw-red-700 is equivalent to text-red-700 dark:text-red-300 and border-x-daw-emerald-200 is equivalent to border-x-emerald-200 dark:border-x-emerald-800.

Now you know how to use it: simply add daw (short for "dark aware") before the colour part of any Tailwind colour utility you use.

// = bg-stone-100 dark:bg-stone-900 text-stone-900 dark:text-stone-100
() => <body className="bg-daw-stone-100 text-daw-stone-900">Hello world</body>;

A couple of things to note:

  • If you provide colour labeled with DEFAULT, by default your colour is kept intact (i.e. same colour in dark mode as in light mode). You can change this behaviour.

    // tailwind.config.js
{
  theme: {
    extend: {
      colors: {
        red: {
          DEFAULT: "#ff0000",
        },
      },
    },
  }
}

// Component.jsx
() => <div className="text-daw-red" /> // = text-red dark:text-red

  • If you provide a custom value (using the bracket notation), by default your colour is inverted with (h, s, l) => (h, s, 100 - l). You can choose to keep it intact instead.

    () => <div className="text-daw-[#123456]" />; // = text-[#123456] dark:text-[#a9cbed]

Customising

First of all, you need to call the plugin the way that Tailwind will expect options.

module.exports = {
  theme: {
    // ...
  },
  plugins: [
    require("tailwind-dark-aware")({
      // your options here
    }),
    // ...
  ],
};

suffix

TypeScript type: string
Default: daw

This sets the suffix added to all colour utilities.

require("tailwind-dark-aware")({ suffix: "my-suffix" })
() => <div className="text-my-suffix-red-300" /> // = text-red-300 dark:text-red-700

ignoredKeys

TypeScript type: string[]
Default: []

The "shades" to be ignored.

To find the dark mode variant of a colour, tailwind-dark-aware sorts the palette by luminosity, then get the colour placed opposite to the colour in question.

With the default configuration ([]), this would mean [50, 950], [100, 900], [200, 800], [300, 700] and so on. However, if you change it to (say) ["50"], the pairing would become [100, 950], [200, 900], [300, 800], etc. Therefore, you would probably not want to use this option.

require("tailwind-dark-aware")({ ignoredKeys: ["400", "700"] })
// 50, 100, 200, 300, 500, 600, 800, 900, 950
() => <div className="text-daw-red-300" /> // = text-red-300 dark:text-red-600

Note: The colour schemes of Tailwind is updated with the 950 shade in Tailwind v3.3.0. If you use an earlier Tailwind version, while the package would still work, since shade 950 is not available you should configure ignoredKeys to be ["50"], otherwise the pairing would be [50, 900], [100, 800], etc. which is likely not what you want.

invertCustomColours

TypeScript type: boolean
Default: true

Whether to invert custom colours (provided by the bracket notation) or not. If set to true, the colour is inverted by "inverting" the luminosity while keeping the hue and saturation.

require("tailwind-dark-aware")({ invertCustomColours: true })
() => <div className="text-daw-[#123456]" /> // = text-[#123456] dark:text-[#a9cbed]
require("tailwind-dark-aware")({ invertCustomColours: false })
() => <div className="text-daw-[#123456]" /> // = text-[#123456] dark:text-[#123456]

invertDefaultColours

TypeScript type: boolean
Default: false

Whether to invert colour defined with DEFAULT key in tailwind.config.js. If set to true, the colour is inverted by "inverting" the luminosity while keeping the hue and saturation.

// tailwind.config.js
{
  theme: {
    extend: {
      colors: {
        primary: {
          DEFAULT: "#123456",
        },
      },
    },
  }
}
require("tailwind-dark-aware")({ invertDefaultColours: true })
() => <div className="text-daw-primary" /> // = text-primary dark:text-[#a9cbed]
require("tailwind-dark-aware")({ invertDefaultColours: false })
() => <div className="text-daw-primary" /> // = text-primary dark:text-primary

nonInvertBehaviour

TypeScript type: "same-dark" | "no-dark"
Default: "same-dark"

Specify what happens if a colour, either a DEFAULT colour or a custom colour, is not inverted.

same-dark means the declaration is also made for dark mode.

require("tailwind-dark-aware")({ nonInvertBehaviour: "same-dark" })
() => <div className="text-daw-primary" /> // = text-primary dark:text-primary

no-dark does not declare for dark mode.

require("tailwind-dark-aware")({ nonInvertBehaviour: "no-dark" })
() => <div className="text-daw-primary" /> // = text-primary