Add dark mode variant #2279

adamwathan · 2020-09-01T01:07:40Z

This PR introduces experimental support for a new dark variant that allows you to conditionally add different styles based on whether "dark mode" is enabled.

In practice it looks like this:

<div class="bg-white text-black dark:bg-black dark:text-white"></div>

It is made available under the darkModeVariant experimental flag:

// tailwind.config.js
module.exports = {
  experimental: {
    darkModeVariant: true
  },
  // ...
}

Functionality

Stackable by default

The dark variant automatically stacks against basic variants like hover and focus, and also combines with responsive prefixes like sm, lg, etc., so you can do things like this no problem:

<button class="lg:dark:hover:bg-purple-300 ...">
  <!-- ... -->
</button>

The dark variant does not stack with motion-safe and motion-reduce variants, but I don't expect that will actually be an issue for anyone. In the future we will likely provide more control over how variants are stacked in general.

Media query and class-based strategies

By default we use a "media" strategy, which generates classes like this:

@media (prefers-color-scheme: dark) {
  .dark\:bg-black {
    background-color: black;
  }
}

This is fine for many projects, but has the limitation of not being able to store a user's preference, or allow them to switch between light mode and dark mode with a toggle since it is tied to their operating system preferences.

To support more sophisticated needs, I've also implemented a "class" strategy that you can enable like so:

// tailwind.config.js
module.exports = {
  dark: 'class',
  // ...
}

This will generate classes like this instead:

.dark .dark\:bg-black {
  background-color: black;
}

To use this strategy, you'll need to add a parent class of "dark" whenever you'd like to enable dark mode, usually to the html element:

<html class="dark">
  <!-- ... -->
  <body>
    <div class="bg-white text-black dark:bg-black dark:text-white"></div>
  </body>
</html>

Default configuration

By default, the dark option is set to media:

// tailwind.config.js
module.exports = {
  dark: 'media',
  // ...
}

The dark variant is enabled for the following core plugins:

backgroundColor
borderColor
divideColor
textColor
placeholderColor
gradientColorStops

Enabling in your config file

To enable the dark variant for any of Tailwind's utilities, add dark to the variants configuration for any plugin:

// tailwind.config.js
module.exports = {
  variants: {
    opacity: ['responsive', 'hover', 'focus', 'dark']
  },
  // ...
}

Design Rationale

The obvious question when implementing this feature is "why not build some generalized universal theming solution that supports an arbitrary number of themes?"

The main reasons are:

Operating systems only support light and dark.
Supporting more than a single theme introduces significantly more complexity and challenging decisions.
99% of people only care about dark mode.
We can always add a universal theming feature down the road that supersedes this if we like.

So for now, this feature is unapologetically dark mode only. Every design decision has been made with the mindset of "we only support light mode and dark mode and we don't care about supporting anything else".

That's why the parent class is simply dark, the prefix is just dark, the configuration option is just dark, etc.

Would love any feedback on this. One concern I have myself is that using the class strategy, you can't easily do this:

<html class="dark bg-pink-500 dark:bg-black">
  <!-- ... -->
</html>

...because only child elements are affected. We could update the selector to make this work but it would result in a significant increase in file size. If anyone has any ideas on how to make that work without doubling the number of color-based selectors I'd love to hear them.

In general, this feature introduces a lot of classes because of the fact that it stacks and targets color classes, so it adds a lot of weight to the default CSS file. I personally don't care (I use PurgeCSS and you should too) but I expect it will cause more "wow Tailwind is huge how does anyone use this?" type of remarks. I'm considering building a "TailwindLite" CDN version for 2.0 to try and combat this a bit, but still eventually we are going to hit some critical threshold where the file size becomes an issue even in development mode, so do have to be careful with this stuff.

zaknesler · 2020-09-01T01:26:34Z

I think as long as this is kept as opt-in somehow, it shouldn't be a problem for most people. Purge CSS is our friend. I also think that utility classes are such a great way to implement dark mode color differences. Great work!

pspeter3 · 2020-09-01T01:41:25Z

Is there a way to have a hybrid strategy? Eg default to the media query unless the theme is explicitly set as a class?

ekvedaras · 2020-09-01T06:21:48Z

Would we really need to add other color affecting classes then dark to html tag? I think those should be placed at body. So, dark affecting only children is fine.

OwenMelbz · 2020-09-01T07:06:05Z

Regarding the file size comments, maybe this is where the divergence starts and bigger features start getting pulled into non-default plugins like typography.

That way you specifically import it if you want it, otherwise everybody else is in affected until the dark mode fad goes away :p

lihbr · 2020-09-01T14:06:49Z

Just dropping that here in case it wasn't considered but perhaps also including a dark: "attribute" options along with the planned dark: "class" one could be helpful (as having classes on the html tag is sometimes not convenient), mapping it to data-dark="true"?

adamwathan · 2020-09-01T16:54:19Z

Is there a way to have a hybrid strategy? Eg default to the media query unless the theme is explicitly set as a class?

@pspeter3 The best way to do this is just to use the class strategy and use JS to detect the media query and set it.

Something like this as an inline script in the head before any of the page loads:

<html>
<head>
  <script>
  if (('themePreference' in localStorage) && localStorage.themePreference === 'dark') {
    document.querySelector('html').classList.add('dark')
  } else if (!('themePreference' in localStorage) && window.matchMedia('(prefers-color-scheme: dark)').matches) {
    document.querySelector('html').classList.add('dark')
  }
  </script>
</head>
<!-- ... -->
</html>

adamwathan · 2020-09-01T16:55:44Z

Would we really need to add other color affecting classes then dark to html tag? I think those should be placed at body. So, dark affecting only children is fine.

@ekvedaras The main use case is setting a background color that appears when overscrolling in macOS, that can only be done on the HTML tag unfortunately.

adamwathan · 2020-09-01T16:57:22Z

Just dropping that here in case it wasn't considered but perhaps also including a dark: "attribute" options along with the planned dark: "class" one could be helpful (as having classes on the html tag is sometimes not convenient), mapping it to data-dark="true"?

@lihbr I considered that originally but ultimately decided to use a class because then the class automatically respects the user's prefix setting, so dark will become tw-dark for example for people who need that to avoid collisions. What's a situation where you can't put classes on the HTML tag?

lihbr · 2020-09-01T17:47:06Z

@lihbr I considered that originally but ultimately decided to use a class because then the class automatically respects the user's prefix setting, so dark will become tw-dark for example for people who need that to avoid collisions. What's a situation where you can't put classes on the HTML tag?

Makes sense indeed! I think I had some issues in the past with Modernizr conflicting with Vue meta but that was probably due to a poor usage of mine 🤔

garlandcrow · 2020-09-02T00:25:58Z

I did a simple implementation of dark mode in my last project, at first using the media queries (like this PR), but as another "screen", and when I needed to use tailwind in CSS it looked really nice:

@screen dark {
    .panel {
        @apply text-white;
    }
}

But when I needed to make dark mode settable by the user, I had to switch to doing something like setting a class on html (like in this PR) and then doing this wasn't as nice (I use svelte). I had to write these each time I wanted to target something as dark like:

:global(html.dark) .panel {
    @apply text-white;
}

I don't know how those @screen like helpers are generated, but is there any way to make it easy to target the dark mode by using one of those? Maybe something like

@dark {
    .panel {
        @apply text-white;
    }
}

adamwathan · 2020-09-02T02:28:10Z

IndexedDB is async so you can get a flash of the wrong color whereas localStorage is sync and blocking 😊

Anyways if people want to use the media query strategy of course you’re welcome to, that’s why I’m including both. It’s even the default!

alexandprivate · 2020-09-02T04:29:14Z

This is amazing, previous media implementation was on but yet we have to do a lot of work on saving the user preferences, thanks @adamwathan !

gauravkumar37 · 2020-09-02T19:02:07Z

I'll say it again though, a user who actively sets their OS to dark mode is making their selection for light/dark themes already—negating the need to have a toggle.

I think not giving users the option to override OS theme for a particular website is not taking accessibility into account. Depending on the website, one may choose a different theme. This is crucial for users with visual disability. I have seen such users who prefer dark theme overall (since decreased brightness is better for eyes) but prefer light theme for blogs where they have to read a lot of text because reading light text on dark background irritates their eyes.

brandonpittman · 2020-09-02T23:54:58Z

@gauravkumar37

We should probably also not be handling this with JavaScript in case the user has disabled it or has an unstable connection. That seems like an accessibility concern as well.

The only reasonable solution is to manage user preference server-side, or maybe a cookie, and then send pre-rendered HTML with the correct CSS down the wire.

sowenjub · 2020-09-04T22:06:34Z

Have you considered the way Apple approaches this? Instead of defining a dark variant, you would define a dark color for each color in the configuration file.

Below is a screenshot of the color assets in Xcode.

So bg-white in light mode would be white, but default to black in dark mode.

This means the class strategy is not an issue anymore, and you potentially save a lot of code, both in the CSS files and as you create your design (since you don't have to use any class at all).

You could keep the dark variant to give some more flexibility when needed.

paulpopus · 2020-09-05T21:39:46Z

@sowenjub That's achievable by setting your color variables to CSS variables, no? Which you can then swap on the fly with different stylesheets. The issue with it is that your classes either need to be function based like bg-primary or your bg-white becomes meaningless essentially.

sei-jdshimkoski · 2020-09-08T14:08:54Z

@sowenjub That's achievable by setting your color variables to CSS variables, no? Which you can then swap on the fly with different stylesheets. The issue with it is that your classes either need to be function based like bg-primary or your bg-white becomes meaningless essentially.

Doing this breaks text-opacity and bg-opacity classes, so if you need those, you can't use CSS variables for color declarations.

adamwathan · 2020-09-09T13:43:25Z

@cbenjafield Can you create a GitHub repo that shows it not working so I can easily pull it down and tinker with it? Don't have a ton of time to set it up from scratch but if I can just clone it and sort it out in 5 minutes I can definitely help.

cbenjafield · 2020-09-09T14:41:01Z

@cbenjafield Can you create a GitHub repo that shows it not working so I can easily pull it down and tinker with it? Don't have a ton of time to set it up from scratch but if I can just clone it and sort it out in 5 minutes I can definitely help.

Ah, solved it literally just as you replied - just me being stupid and not updating purgecss to handle the dark class 🤦🏼‍♂️

itaysmalia · 2020-10-07T15:53:37Z

hey, any example on how to use the dark mode without the media query? the dark:"class" didn't work for me and I don't see any changes in the css file.

thank you :)

Ali-Hussein-dev · 2020-10-07T20:27:30Z

We can change the values of the color classes based on the dark mode whether is enabled or not.
something like this
theme: { gray: dark ? { 100: '#1a202c', ... 900: '#f7fafc', } : { 100: '#f7fafc', ... 900: '#1a202c', } }
so bg-gray-900 has two values one for light and one for dark.

ariaieboy · 2020-10-13T05:46:10Z

can anyone send me the link of this feature in the official docs ?

adamwathan · 2020-10-13T09:45:59Z

The feature is still experimental so this pull request is the docs for now 👍🏻

Im-Fran · 2020-10-16T23:04:15Z

HI!
How can I implement this on laravel?
I've modified my tailwind.config.js so now it's like this: https://paste.theprogramsrc.xyz/facaafcaaf.js
and I just used npm i && npm run dev but is not working. The script I've added to the head is working properly (adding the class dark to the html tag) and I'm testing it by using the following code: <div class="bg-gray-100 dark:bg-black">test</div> but the background is not black, it stays as gray

paulpopus · 2020-10-16T23:07:21Z

@Im-Fran You probably need to enable the 'dark' variant for backgrounds too. You currently only have it for opacity. I believe dark:opacity-50 should work.

Im-Fran · 2020-10-17T00:11:54Z

Oh, oki, thanks

IRediTOTO · 2020-10-21T20:36:06Z

Hi, how about prefix? Will dark become tw-dark? I didnt test but tell me if you know :D

GSCrawley · 2020-10-21T20:37:51Z

I’ve tried to unsubscribe from this thread but am still getting emails.

On Wed, Oct 21, 2020 at 1:36 PM IRediTOTO ***@***.***> wrote: Hi, how about prefix? Will dark become tw-dark? I didnt test but tell me if you know :D — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#2279 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AHRLYS4PYXV7D7RKG6CCOW3SL5A5NANCNFSM4QRD3H2A> .

-- Gideon S Crawley 646-667-5520

steveszc · 2020-11-16T17:43:14Z

I'm a little late to the party here, but it might be nice to offer a way to provide a custom class for the class strategy. For anyone that has already implemented a custom dark mode variant this might smooth the transition. In my case, we use is-dark-mode and we have this class in our preference persistence logic and all over our non-tailwind CSS.

Maybe something like this?

// tailwind.config.js
module.exports = {
  dark: { class: 'is-dark-mode' }
  // ...
}

I'd be happy to take a shot at a PR adding this if others agree it would be useful. It'd be great to land this before 2.0

adamwathan added 4 commits August 31, 2020 15:50

Initial dark mode prototype

2c7fbaf

Isolate dark mode logic to config extension

89d03c7

Update fixtures

8e2fbf3

Fix lint warnings

b4ee918

JNavith mentioned this pull request Sep 1, 2020

RFC: Theming plugin comparison table JNavith/tailwindcss-theme-variants#5

Open

adamwathan merged commit 5701d78 into master Sep 1, 2020

adamwathan deleted the dark-mode branch September 1, 2020 17:16

ben-rogerson mentioned this pull request Sep 4, 2020

Support Tailwind CSS v1.8.0 ben-rogerson/twin.macro#141

Closed

divine mentioned this pull request Sep 5, 2020

Add darkMode option nuxt-modules/tailwindcss#135

Closed

ben-rogerson mentioned this pull request Sep 5, 2020

Add dark and light mode variants ben-rogerson/twin.macro#142

Merged

laymonage mentioned this pull request Sep 10, 2020

Support TailwindCSS 1.8.0 tailwindlabs/tailwindcss-intellisense#186

Closed

This was referenced Oct 23, 2020

tailwind compatibility + overscroll wKovacs64/gatsby-plugin-use-dark-mode#61

Closed

handle overscroll and tailwind insin/gatsby-plugin-dark-mode#12

Open

tmr08c mentioned this pull request Oct 29, 2020

Set up dark mode 🌚 tmr08c/tmr08c.github.io#82

Closed

sumanthratna mentioned this pull request Nov 5, 2020

Tailwind features meta issue HackTJ/live#1

Open

7 tasks

This was referenced Jan 2, 2021

TailwindCSS v2 support muhammadsammy/tailwindcss-classnames#66

Closed

feat: support dark mode classes muhammadsammy/tailwindcss-classnames#67

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add dark mode variant #2279

Add dark mode variant #2279

adamwathan commented Sep 1, 2020

zaknesler commented Sep 1, 2020

pspeter3 commented Sep 1, 2020

ekvedaras commented Sep 1, 2020 •

edited

OwenMelbz commented Sep 1, 2020

lihbr commented Sep 1, 2020

adamwathan commented Sep 1, 2020

adamwathan commented Sep 1, 2020

adamwathan commented Sep 1, 2020

lihbr commented Sep 1, 2020 •

edited

garlandcrow commented Sep 2, 2020

adamwathan commented Sep 2, 2020

alexandprivate commented Sep 2, 2020

gauravkumar37 commented Sep 2, 2020

brandonpittman commented Sep 2, 2020 •

edited

sowenjub commented Sep 4, 2020 •

edited

paulpopus commented Sep 5, 2020 •

edited

sei-jdshimkoski commented Sep 8, 2020

adamwathan commented Sep 9, 2020

cbenjafield commented Sep 9, 2020

itaysmalia commented Oct 7, 2020 •

edited

Ali-Hussein-dev commented Oct 7, 2020 •

edited

ariaieboy commented Oct 13, 2020

adamwathan commented Oct 13, 2020

Im-Fran commented Oct 16, 2020

paulpopus commented Oct 16, 2020

Im-Fran commented Oct 17, 2020

IRediTOTO commented Oct 21, 2020 •

edited

GSCrawley commented Oct 21, 2020 via email

steveszc commented Nov 16, 2020

Add dark mode variant #2279

Add dark mode variant #2279

Conversation

adamwathan commented Sep 1, 2020

Functionality

Stackable by default

Media query and class-based strategies

Default configuration

Enabling in your config file

Design Rationale

zaknesler commented Sep 1, 2020

pspeter3 commented Sep 1, 2020

ekvedaras commented Sep 1, 2020 • edited

OwenMelbz commented Sep 1, 2020

lihbr commented Sep 1, 2020

adamwathan commented Sep 1, 2020

adamwathan commented Sep 1, 2020

adamwathan commented Sep 1, 2020

lihbr commented Sep 1, 2020 • edited

garlandcrow commented Sep 2, 2020

adamwathan commented Sep 2, 2020

alexandprivate commented Sep 2, 2020

gauravkumar37 commented Sep 2, 2020

brandonpittman commented Sep 2, 2020 • edited

sowenjub commented Sep 4, 2020 • edited

paulpopus commented Sep 5, 2020 • edited

sei-jdshimkoski commented Sep 8, 2020

adamwathan commented Sep 9, 2020

cbenjafield commented Sep 9, 2020

itaysmalia commented Oct 7, 2020 • edited

Ali-Hussein-dev commented Oct 7, 2020 • edited

ariaieboy commented Oct 13, 2020

adamwathan commented Oct 13, 2020

Im-Fran commented Oct 16, 2020

paulpopus commented Oct 16, 2020

Im-Fran commented Oct 17, 2020

IRediTOTO commented Oct 21, 2020 • edited

GSCrawley commented Oct 21, 2020 via email

steveszc commented Nov 16, 2020

ekvedaras commented Sep 1, 2020 •

edited

lihbr commented Sep 1, 2020 •

edited

brandonpittman commented Sep 2, 2020 •

edited

sowenjub commented Sep 4, 2020 •

edited

paulpopus commented Sep 5, 2020 •

edited

itaysmalia commented Oct 7, 2020 •

edited

Ali-Hussein-dev commented Oct 7, 2020 •

edited

IRediTOTO commented Oct 21, 2020 •

edited