Add dark mode support

[mdo]

Heavily WIP still, but this begins the process of implementing dark mode for our docs and across the project itself. Here's a quick look at what's coming. Builds on #35736.

Light	Dark

Toggling

Color modes are toggled in the docs navbar with a custom toggler, which stores the select color mode in local storage. Color modes are set via data attribute via data-theme (with light or dark options available currently). This allows us to theme the entire page, or specific components, like so.

New Sass and CSS variables

In order to best implement color modes, I've spiked out a number of new Sass and CSS variables (e.g., --bs-secondary-bg and --bs-tertiary-bg). In addition, I've added new global CSS variables like --bs-border-color and more. So, in addition to general color modes and theming support, we get greater real-time customization, too.

This allows us to have more nuance coloring, and a more system-wide color scheme, than we currently support. Some inspiration of the new CSS variables comes from macOS and other design systems where there are global constants (e.g., using the same border-color or blue being the color for links, primary actions, etc).

Todos and open questions:

• [ ] Do we refer to these as themes or color modes?
• [ ] Do we provide a color mode toggler JS plugin? (Would close #35333)
• [ ] Finish docs for color modes
• [ ] Update all components to better utilize global CSS variables so they can be more easily themed (e.g., see $dropdown-* Sass variable changes in the diff).

---

• Fixes #27514
• Fixes #28424
• Replaces #28449
• Fixes #28540
• Fixes #28754
• Fixes #29720
• Fixes #31175
• Fixes #33071
• Fixes #33501

[Kopyov]

@mdo consider also adding root CSS vars for $spacer as it would give a better control over margin/padding utility classes and prepare the code to re-use spacing CSS vars in all components. Something like this:

// root var
--#{$variable-prefix}spacer: #{$spacer};

// variables.scss
$spacer: 1rem !default;
$spacers: (
  0: 0,
  1: calc(var(--#{$variable-prefix}spacer) * .25),
  2: calc(var(--#{$variable-prefix}spacer) * .5),
  3: var(--#{$variable-prefix}spacer),
  4: calc(var(--#{$variable-prefix}spacer) * 1.5),
  5: calc(var(--#{$variable-prefix}spacer) * 3),
) !default;

// component vars in variables.scss
$card-spacer-y:                     var(--#{$variable-prefix}spacer) !default;
$card-spacer-x:                     var(--#{$variable-prefix}spacer) !default;
$card-title-spacer-y:             calc(var(--#{$variable-prefix}spacer) * .5) !default;

and convert all SASS calculations to calc(). This change will probably lead to other changes in a bunch of files, but would be definitely a good addition in one of future updates.

[mdo]

Pushed a big update here that revamps the toggler to be a dropdown so we can accept light mode, dark mode, or automatic (based on system preference). My JS isn't the best, but it feels decent and works well lol. Would love some eyes on it.

Light	Dark

And here's how the theme toggler looks in the navbar. Note that as you change the theme, the icon in the navbar updates accordingly to indicate what theme is active.

[AgentSmith0]

Do we refer to these as themes or color modes?

I think color modes fits better, since the word themes is already used.

Do we provide a color mode toggler JS plugin?

Probably not, since there are so many ways of realizing them, from buttons to dropdowns and cookies to local storage. Beside that it seems to be very easy to implement by now.

Thank you for your work!

[theDanielJLewis]

This looks great! I'm very eager to use it!

Any idea when it might be released? I know it's currently proposed for 5.3 and we're still on 5.1. But I'm hoping for something like a couple months from now, if possible.

[AgentSmith0]

Is it possible to update this PR to include the latest changes of the master branch?

[j-f1]

I’ve done my best to resolve merge conflicts and have committed the compiled CSS here: https://github.com/j-f1/forked-bootstrap/tree/new-masthead-darkmode

[mdo]

I’ve done my best to resolve merge conflicts and have committed the compiled CSS here: https://github.com/j-f1/forked-bootstrap/tree/new-masthead-darkmode

Thanks @j-f1, no need to keep that up to date. I'll push an update shortly. Hoping to get the docs redesign that PR is based on merged in first. Then this will become a bit of an evergreen PR until v5.3.0 I think. Lots to do here!

[AgentSmith0]

@mdo Would you say this functionality will be extendable to other color modes including for color blindness or high contrast?

[mdo]

@mdo Would you say this functionality will be extendable to other color modes including for color blindness or high contrast?

I don't see why not. The idea is you could spin up any number of theme values for data-theme, or even media queries, and create those color modes as needed.

[vinorodrigues]

@mdo - do you want help with this?

[mdo]

@mdo - do you want help with this?

@vinorodrigues Id love help tearing things! I've been regularly coming back to this to fix little bugs here and there, but I'm bound to miss something. General feedback is also very welcome!

[AgentSmith0]

https://deploy-preview-35857--twbs-bootstrap.netlify.app/docs/5.2/components/list-group/#links-and-buttons When you click on a list group button, it gets light, but it should be dark.

EDIT: fixed

[mdevan]

There's something wrong with the multiple-select:

https://deploy-preview-35857--twbs-bootstrap.netlify.app/docs/5.2/forms/select/#sizing

It's OK in the regular version:

[mdevan]

https://deploy-preview-35857--twbs-bootstrap.netlify.app/docs/5.2/forms/floating-labels/#readonly-plaintext

The value in "Input with value" is not readable:

[AgentSmith0]

@mdevan The issue with the readonly floating label is not related to the dark mode support. You should open a seperate issue for that.

[mdo]

@mdevan The issue with the readonly floating label is not related to the dark mode support. You should open a seperate issue for that.

It is an issue with dark mode, I’ve just pushed a fix for it.

[AgentSmith0]

In light mode, the navbar collapse toggler icon isn't visible anymore.

[mdevan]

For tables with table-hover, the bg color of the hovered row is not very different from bg of normal row. See:

https://deploy-preview-35857--twbs-bootstrap.netlify.app/docs/5.2/content/tables/#hoverable-rows

[jaxramus]

One thing I've noticed is that the alerts in dark mode are kind of ugly. I think they should use darker styles. For example, when in dark mode, a success alert should have bg-success text-light type styling.

Thoughts?

Edit: same goes for table row color variants. They are super bright in dark mode.

[AgentSmith0]

Switching from dark to auto isn't working anymore on dark theme preferred browsers. Only after refreshing the page, the change will be applied.

EDIT: fixed

[mdo]

Yeah I have to finish my JS updates. Pushed some code to prevent the white flash when in dark mode, but that broke the other JS. Thanks for calling it out!

[AgentSmith0]

Expanded accordion item doesn't look well (not dark) in dark mode. https://deploy-preview-35857--twbs-bootstrap.netlify.app/docs/5.2/components/accordion/#content

[burdittw]

Can we get something that tells us how to modify and create a new theme? I tried all kinds of ways to add my own variables to the dark theme and could not get them to show up. I created my own _variables-dark.scss file with no luck. I added the [data-theme='dark'] tag and removed it with no joy. Any help would be much appreciated. I know this is not finished but there has to be a way to do it.

[mdo]

Can we get something that tells us how to modify and create a new theme? I tried all kinds of ways to add my own variables to the dark theme and could not get them to show up. I created my own _variables-dark.scss file with no luck. I added the [data-theme='dark'] tag and removed it with no joy. Any help would be much appreciated. I know this is not finished but there has to be a way to do it.

@burdittw This is still an open and WIP pull request, so don't expect anything to be functional until it ships in v5.3.0. That said, there is some guidance in the Customize > Color page under Custom color modes. I have some more iterations that are coming for that though.

[burdittw]

@mdo

This is still an open and WIP pull request, so don't expect anything to be functional until it ships in v5.3.0. That said, there is some guidance in the Customize > Color page under Custom color modes. I have some more iterations that are coming for that though.

Thanks for the response. I know it is not an official alpha/beta/release candidate but was look for some more details than what the current doc says that you pointed to. I have eventually figured it out and have it working in the project I was adding it to.

Good work on getting this into Bootstrap! It is a nice simple solution and seems to work well at its current stage. Once I figured out the tagging's to add to parts it was easy from there on out. This should allow users to make theming Bootstrap really simple.

Thanks again for all the work the team puts into Bootstrap!!!

[bhojkamal]

When is this coming?

[AgentSmith0]

Is it possible to update this PR, so that we can get the latest features from the 5.2.0 release? Thank you!

[septatrix]

After playing around a bit with it I am already eagerly awaiting BS 5.3. A few things however I noticed (until now, maybe more follow when using it more):

1. The dark button is not discernible as it has the same color as the background unless hovering. A tint similar to the input group elements or card headers should help here.
2. Headings inside light cards are not readable (though that might be solved after a rebase on master?). Same for the border between card body and header/footer.
3. [data-theme="dark"] should also set transitive variables like --bs-form-control-bg. These refer to other variables however setting the referred variables to a new value in a child scope does not update the other variables transitively.

[septatrix]

Oh also dark mode toggle on the examples/gallery would be fantastic (especially the cheatsheet)

[mdo]

Adding a note to revisit the backdrop-filter (per https://github.com/twbs/bootstrap/pull/36549).

[czirok]

Hello @mdo

I modified and fixed a few errors in the documentation. This is just documentation. Not components.

• Added the color scheme: light and dark. https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme
• Added the color scheme sample to the stretched-link and gutters documentation and deleted the bg-light class.
• Deleted the bg-light class from several documentations to make the documentation nicer.

Full diff here

There are several *-dark color errors left, further research is needed:

~~- /docs/5.2/helpers/colored-links/~~ - Fix: https://github.com/twbs/bootstrap/pull/35857#issuecomment-1236054861 ~~- /docs/5.2/utilities/colors/#colors~~ - Fix: https://github.com/twbs/bootstrap/pull/35857#issuecomment-1236054861 ~~- /docs/5.2/components/card/#border~~ - Fix: https://github.com/twbs/bootstrap/pull/35857#issuecomment-1236054861

• /docs/5.2/components/carousel/#dark-variant

~~- /docs/5.2/components/navbar/#external-content~~ - Fix: https://github.com/twbs/bootstrap/pull/35857#issuecomment-1236350647 ~~- /docs/5.2/components/navbar/#offcanvas~~ - Fix: https://github.com/twbs/bootstrap/pull/35857#issuecomment-1236350647

Todos and open questions: Do we refer to these as themes or color modes?

The documentation calls this "color schemes". https://developer.mozilla.org/en-US/docs/Web/CSS/color-scheme. I personally vote for this. I think "themes" and "color modes" words place: html>head>meta keywords for search engines.

Some thoughts

Dark scheme logo? /docs/5.2/about/brand/ Disabled color in dark shema maybe litle more darker?

[czirok]

Additional modifications

Use consistent colors in the documentation:

• /docs/5.2/helpers/colored-links/ - use theme-colors.yml
• /docs/5.2/utilities/background/ - change text-dark class to style="var(--bs-body-color)"
• /docs/5.2/utilities/colors/ - add bg-light class
• theme-colors.yml - add contrast_color: light to dark

Outline light dark buttons

I don't know the right way to fix it. Change the documentation? Describe that light button can only be used with the dark scheme and dark button can only be used with the light scheme? Writing separate documentation example?

• /docs/5.2/components/buttons/#outline-buttons
• /docs/5.2/components/button-group/#sizing

[czirok]

hello @mdo , please help. Something happened in https://github.com/twbs/bootstrap/pull/35857/commits/143f94708335cb706127886db4a8d785046d1bbc with dark scheme offcanvas end height and I can't find the error.

Light scheme offcanvas end perfect.

[julien-deramond]

hello @mdo , please help. Something happened in 143f947 with dark scheme offcanvas end height and I can't find the error.

Light scheme offcanvas end perfect.

It's mentioned in https://github.com/twbs/bootstrap/pull/35857#issuecomment-1234691612. I'm hiding both our comments for readability in this PR.

[marceloverdijk]

Awesome, is there any timeline to share when this expected to be released? <no pressure, just eagerly anticipating on this>

[czirok]

Dark scheme offcanvas height fix

Maybe it's not supported (site/assets/scss/_navbar.scss):

[data-bs-theme="dark"] & { // backdrop-filter: blur(.25rem); ... }

Test

Windows 10 latest. Google Chrome, Microsoft Edge and Firefox latest.

[czirok]

Hide offcanvas for better testing experience on mobile and small background color change in /docs/5.2/components/offcanvas/#dark-offcanvas

Offcanvas hide in index.js and background fix in doc

Full diff here

[czirok]

I changed the dark scheme colors for a better reading experience.

Better dark scheme colors without dist

Full diff here

[czirok]

Hello everyone.

Text muted color restored. There were problems during testing.

Navbar toggle icon - hamburger

There was a big bug in new-masthead-darkmode. SVG does not support variables in CSS. Unfortunately.

It is impossible to change the color of SVG in CSS, with a variable. Nightmare.

I use an elegant solution for light and dark themes. Very little modification. There are two hamburgers in one SVG. A light and a dark. The dark, under the light. When changing the scheme, I change the background-position. I modified the navbar-dark class, added this solution. No need to add data-bs-theme="dark" attribute and 100% backwards compatible.

I checked the example pages and corrected small errors.

Text muted restore. Navbar support light and dark scheme svg in css. Examples fix.

Good testing...

Execute npm run dist before npm start.

[AgentSmith0]

@czirok Thank you very much for your work, could you please rebuild your bootstrap.css file in your repository (https://github.com/czirok/bootstrap-new-masthead-darkmode/tree/new-masthead-darkmode) to make it easier to try.

[czirok]

EDIT:

This not bug, I find this in docomentation: https://getbootstrap.com/docs/5.2/utilities/colors/#how-it-works

Hello @mdo and @XhmikosR and everybody.

I'm working on color themes and I don't know if this is a bug or a feature.

I looked at several releases. Maybe "to-rgb(...)" in scss is wrong everywhere. The CSS file has this:

"any-rgb: number, number, number;".

Not this:

"any-rgb: rgb(number, number, number);".

[czirok]

Hello everyone!

I modified it a bit again. Accordion, alerts (support dark), close button, nav and navbar.

The mod doesn't just support dark mode. Supported by the theme on the theme on the theme on the theme on the theme on the theme...

<div class="text-bg-dark" data-bs-theme="dark">
  
  <div class="text-bg-light" data-bs-theme="light">

    <div class="text-bg-color1" data-bs-theme="color1">
  
      <div class="text-bg-color*" data-bs-theme="color*">

      </div>
  
    </div>

  </div>

</div>

*-dark and *-white are not required.

I developed a test site. Bootstrap docs: https://czirok.github.io/docs Dev: https://czirok.github.io/dev Github: https://github.com/czirok/czirok.github.io

On the dev page, under "test pages", the up arrow is switch between dev -> docs. Or open it in two tabs, change the colors, view content, update the other tab.

Somebody help me. can npm run netlify change the relative path? Currently root (/) is bootstrap, I want it to be /bootstrap-themes. Thx.