Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/joulev/tailwind-dark-aware
Tailwind CSS plugin to generate shorthands for light mode and dark mode colour classes
https://github.com/joulev/tailwind-dark-aware
dark-mode tailwind-plugin tailwindcss
Last synced: 3 months ago
JSON representation
Tailwind CSS plugin to generate shorthands for light mode and dark mode colour classes
- Host: GitHub
- URL: https://github.com/joulev/tailwind-dark-aware
- Owner: joulev
- License: mit
- Created: 2022-10-11T16:57:17.000Z (about 2 years ago)
- Default Branch: main
- Last Pushed: 2024-06-12T02:39:01.000Z (7 months ago)
- Last Synced: 2024-09-16T19:44:06.912Z (4 months ago)
- Topics: dark-mode, tailwind-plugin, tailwindcss
- Language: TypeScript
- Homepage: https://tailwind-dark-aware.vercel.app
- Size: 420 KB
- Stars: 14
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: readme.md
- License: license.md
Awesome Lists containing this project
README
# tailwind-dark-aware
Tailwind CSS plugin to generate shorthands for light mode and dark mode colour classes.
 
---
## Demo app
**Deployment:** https://tailwind-dark-aware.vercel.app
**Source:** https://github.com/joulev/tailwind-dark-aware/tree/main/demo
## Installation
```sh
npm install -D tailwind-dark-aware
```
Then add the plugin in your `tailwind.config.js` file:
```js
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.
```jsx
// = bg-stone-100 dark:bg-stone-900 text-stone-900 dark:text-stone-100
() => Hello world;
```
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](#invertdefaultcolours).
```jsx
// tailwind.config.js
{
theme: {
extend: {
colors: {
red: {
DEFAULT: "#ff0000",
},
},
},
}
}
// Component.jsx
() =>
// = 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](#invertcustomcolours).
```jsx
() =>
; // = text-[#123456] dark:text-[#a9cbed]
```
## Customising
First of all, you need to call the plugin the way that Tailwind will expect options.
```js
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.
```jsx
require("tailwind-dark-aware")({ suffix: "my-suffix" })
() =>
// = 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.
```jsx
require("tailwind-dark-aware")({ ignoredKeys: ["400", "700"] })
// 50, 100, 200, 300, 500, 600, 800, 900, 950
() =>
// = 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.
```jsx
require("tailwind-dark-aware")({ invertCustomColours: true })
() =>
// = text-[#123456] dark:text-[#a9cbed]
```
```jsx
require("tailwind-dark-aware")({ invertCustomColours: false })
() =>
// = 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.
```jsx
// tailwind.config.js
{
theme: {
extend: {
colors: {
primary: {
DEFAULT: "#123456",
},
},
},
}
}
```
```jsx
require("tailwind-dark-aware")({ invertDefaultColours: true })
() =>
// = text-primary dark:text-[#a9cbed]
```
```jsx
require("tailwind-dark-aware")({ invertDefaultColours: false })
() =>
// = 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.
```jsx
require("tailwind-dark-aware")({ nonInvertBehaviour: "same-dark" })
() =>
// = text-primary dark:text-primary
```
`no-dark` does not declare for dark mode.
```jsx
require("tailwind-dark-aware")({ nonInvertBehaviour: "no-dark" })
() =>
// = text-primary
```