Canvas Docs

Dark Mode

Dark Mode

Canvas has full dark mode support. You can make a whole page dark, make a single section dark, or add a switcher that lets visitors toggle it themselves.

Making a page dark

Add the dark class to <body>:

<body class="stretched dark">

Making one section dark

The dark class works on any container, so you can nest a dark region inside a light page:

<div class="section dark">
    <!-- content here uses the dark scheme -->
</div>

A dark mode toggle

Canvas ships a SchemeToggle module. Any element with data-bodyclass-toggle="dark" becomes a switch that adds or removes dark on the body:

<a href="#" data-bodyclass-toggle="dark">Enable Dark Mode</a>

You can swap the label or icon as it toggles with data-add-html and data-remove-html, and remember the choice across visits with data-remember="true":

<a href="#" data-bodyclass-toggle="dark" data-remember="true"
   data-add-html="<i class='bi-brightness-high'></i><span class='visually-hidden'>Light Mode</span>"
   data-remove-html="<i class='bi-moon-stars'></i><span class='visually-hidden'>Dark Mode</span>">
</a>

A checkbox-style switch is also supported with data-type="checkbox". See the color-mode-switcher.html demo in the package for a complete working example.

Bootstrap dark components

Canvas also honors Bootstrap's own dark attribute for native components:

<div data-bs-theme="dark">
    <!-- Bootstrap components render in their dark variant -->
</div>

Turning dark styles on or off in SASS

Dark styling is generated in sass/_dark.scss, guarded by a flag in sass/_variables.scss:

$enable-dark : true !default; // if False then CSS will remove all .dark classes.

Set it to false and rebuild if you never use dark mode and want to trim the CSS.

Tips

  • dark can be nested. A dark section inside a dark page still works.
  • Add a logo-dark image in your #logo block so the logo stays visible when the header goes dark. See the Logo Settings doc.
  • Use data-remember="true" on your toggle so returning visitors keep their preferred scheme.

Usage

<body class="stretched dark">

Extras

Dark Scheme on Individual Elements

Turn the whole site dark by adding the dark class to <body>.

<body class="stretched dark">

Canvas then sets data-bs-theme="dark" on <html> so Bootstrap components render in dark mode too. Any element you want to keep light can carry the not-dark class, which Canvas maps to data-bs-theme="light".

<div class="not-dark">
    This block stays light on a dark page.
</div>

For a user-controlled toggle instead of a permanent dark page, use a .body-scheme-toggle button with data-bodyclass-toggle="dark". To follow the OS preference automatically, use the adaptive-color-scheme body class.

Adaptive Color Scheme

Add the adaptive-color-scheme class to <body> and Canvas will automatically switch to dark mode when the visitor's OS is set to a dark colour scheme (via prefers-color-scheme). It also listens for live changes.

<body class="stretched adaptive-color-scheme">

You can optionally swap classes on a single element when the scheme changes by adding data-adaptive-light-class and data-adaptive-dark-class:

<button class="button btn-danger"
        data-adaptive-light-class="btn-danger"
        data-adaptive-dark-class="btn-success">
    Adaptive Button
</button>

Notes:

  • When dark mode activates, Canvas adds the dark class to <body> and sets data-bs-theme="dark" on <html>.
  • The visitor's manual choice is remembered via the __cnvs_body_color_scheme cookie, so a manual toggle overrides the OS preference.
Was this page helpful?

Related docs

Changing FontsColor SchemesTheme Customization