Create a theme switcher

Learn how to create a component that toggles Calcite Components and ArcGIS API for JavaScript between light and dark themes.

You will use Calcite Components to design an elegant theme switcher that toggles between light and dark for Calcite Components, as well as ArcGIS JavaScript API widgets and basemaps. This application builds on the one created in the Create a mapping app tutorial.

Calcite provides light and dark themes which can be changed using CSS classes: calcite-theme-light (default) and calcite-theme-dark. There is also a calcite-theme-auto class which defers to the browser's CSS prefers-color-scheme media query. Setting the theme class on an element changes all of their child nodes as well.

For more information about theme and styling, visit Calcite Design System's colors and themes foundation and ArcGIS API for JavaScript's styling documentation.

Prerequisites

ArcGIS developer account

You need a free ArcGIS developer account or an account associated with an ArcGIS Online organization to access the services used in this tutorial.

Steps

Create a new pen

To get started, either complete the Create a mapping app tutorial or .

Use an API key

An API key is required to access ArcGIS services if you are using a developer account. You can skip this step if you have an account associated with an ArcGIS Online organization.

Go to your developer dashboard to get an API key.
In CodePen > <script>, import the esriConfig class.

Set the apiKey property.

Use dark colors for code blocks
Change lineAdd line.Change lineAdd line.
  "esri/widgets/Print",
  "esri/config"
], function (WebMap, MapView, Bookmarks, BasemapGallery, LayerList, Legend, Print, esriConfig ) {
esriConfig.apiKey = "YOUR_API_KEY";

Add theme stylesheets

The ArcGIS API for JavaScript uses separate theme stylesheets. Add both light and dark stylesheets, which will be dynamically toggled in JavaScript using their id attributes.

Add the dark theme stylesheet, set the disabled attribute, and add an id.

Add an id to the preexisting light theme stylesheet.

Expand
Use dark colors for code blocks
Add line.Change line
    <script src="https://js.arcgis.com/calcite-components/1.0.0-beta.83/calcite.esm.js" type="module"></script>
    <link rel="stylesheet" href="https://js.arcgis.com/calcite-components/1.0.0-beta.83/calcite.css" />
    <script src="https://js.arcgis.com/4.23/"></script>

    <link disabled id="jsapi-theme-dark" rel="stylesheet" href="https://js.arcgis.com/4.23/esri/themes/dark/main.css" />

    <link id="jsapi-theme-light" rel="stylesheet" href="https://js.arcgis.com/4.23/esri/themes/light/main.css" />
Expand

Add HTML

The primary component in the theme switcher is calcite-switch. The theme switcher will also use calcite-icon for the light and dark icons, and calcite-label to tie it all together.

In the calcite-shell component, add a div element and place it in the shell's header slot with an id attribute used later for styling.
Read the slots FAQ section for more information about the concept. After adding CSS in the next step, you can position the theme switcher over the map by removing the component from shell's header slot.
Add a nested div element within the header slot. Include an id attribute used later for styling.
Add a calcite-label component with the disable-spacing attribute, set the layout attribute to "inline", and add a class attribute used later for styling.
Add the calcite-icon for the light theme, setting the icon attribute to "brightness" and scale attribute to "s". Add a class, which you will use for styling the component.
Add the calcite-switch component.

Add the calcite-icon for the dark theme, setting the icon attribute to "moon" and scale attribute to "s". Add the same class used for the light theme.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
  <body>
    <calcite-loader active></calcite-loader>
    <calcite-shell content-behind hidden>

      <!--  Header slot  -->
      <div slot="header" id="header">

        <!-- Title -->
        <h2 id="header-title">
          <!-- Dynamically populated -->
        </h2>

        <!-- Controls -->
        <div id="header-controls">
          <!-- Dark Mode Switch -->
          <calcite-label disable-spacing layout="inline" class="label-wrapper">
            <calcite-icon icon="brightness" scale="s" class="switch-icon"></calcite-icon>
            <calcite-switch></calcite-switch>
            <calcite-icon icon="moon" scale="s" class="switch-icon"></calcite-icon>
          </calcite-label>
        </div>
      </div>
Expand

Add CSS

At this point, if you run the app you will see the theme switcher in the top, left corner of the application.

Next, add styling with CSS to position the component using Flexbox.

In the <style> element, add CSS for the header using the id created for the header slot. To space content in the header, add padding and set the header slot's background-color to the --calcite-ui-foreground-1 CSS variable.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    #header {
      display: flex;
      padding: 0 1rem;
      background-color: var(--calcite-ui-foreground-1);
    }
Expand

Add styles to the header controls using the id for the header slot's nested div. The additional div element's styling can accommodate one, or multiple components. To space the header controls, use the margin-inline-start and align-self CSS properties.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.
    #header-controls {
      display: flex;
      margin-inline-start: auto;
      align-self: center;
    }
Expand

To configure the dark mode switch's layout, set the margin-inline and padding CSS properties. Add a border using the --calcite-ui-border-1 CSS variable for the color. Next, add a margin CSS property to the calcite-switch, which will accommodate future controls in the interface.
Read the CSS variables FAQ section for more information about the concept. Calcite's theme colors have both light and dark values, which automatically switch when toggling themes. Use the theme color variables for all non-Calcite elements in applications that switch themes.

Finally, set the switch's cursor property to "pointer" to communicate that the switch container is clickable.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
    .label-wrapper {
      display: flex;
      margin-inline: 1rem;
      padding: 0.5rem;
      border: 1px solid var(--calcite-ui-border-1);
      cursor: pointer;
    }

    calcite-switch {
      margin: 0 0.5rem;
    }
Expand

Add JavaScript

Now you have a good looking component; but it doesn't switch any themes. Next, wire up the theme switcher with JavaScript.

In the <script> element, below the existing JavaScript code, create a new function to toggle the themes.
Toggle the calcite-theme-dark class on the <body> element. No need to add the calcite-theme-light class, since it is the default.
Access the ArcGIS JavaScript API's light and dark stylesheets using the id attributes you added above.
Negate the disabled attribute on both stylesheets to toggle their boolean values.
Change the basemap between gray-vector and dark-gray-vector depending on the current theme.

Add an event listener to the calcite-switch component. Listen for the calciteSwitchChange event and provide the function you created.

Calcite provides custom events for many of the components. The custom events will all be prefixed with calcite, then the component name, and finally the type of event. You can check a component's API reference to find out if they have events, and what they are.

Expand
Use dark colors for code blocks
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
        document.querySelector("calcite-shell").hidden = false;
        document.querySelector("calcite-loader").active = false;

        const toggleThemes = () => {
          // Calcite theme
          document.body.classList.toggle("calcite-theme-dark");
          // ArcGIS JSAPI theme
          const dark = document.querySelector("#jsapi-theme-dark");
          const light = document.querySelector("#jsapi-theme-light");
          dark.disabled = !dark.disabled;
          light.disabled = !light.disabled;
          // ArcGIS JSAPI basemap
          map.basemap = dark.disabled ? "gray-vector" : "dark-gray-vector";
        };

        document.querySelector("calcite-switch").addEventListener("calciteSwitchChange", toggleThemes);

      });
    });
  </script>
</html>

Run the app

In CodePen, run your code to display the application.

In the top, right corner of the screen you will see the new, beautiful theme switcher component. Clicking anywhere on the component will toggle the calcite-switch. The function you created for the event listener will run, which will toggle the Calcite Components theme, as well as the ArcGIS JavaScript API basemap and widgets.

Solution

Estimated time

15 minutes

Calcite Design System (Beta)

Create a theme switcher

Solution

Estimated time

Was this page helpful?

Was this page helpful?