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

  1. 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.

  1. Go to your developer dashboard to get an API key.
  2. In CodePen > <script>, import the esriConfig class.
  3. Set the apiKey property.
    Use dark colors for code blocks
        
    Change lineAdd line.Change lineAdd line.
    1
    2
    3
    4
      "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.

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

  2. Add an id to the preexisting light theme stylesheet.

    Expand
    Use dark colors for code blocks
                                                                                                                                                                                                                                                                    
    Add line.Change line
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
        <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.

  1. 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.

  2. Add a nested div element within the header slot. Include an id attribute used later for styling.

  3. 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.

  4. 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.

  5. Add the calcite-switch component.

  6. 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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
      <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.

  1. 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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
        #header {
          display: flex;
          padding: 0 1rem;
          background-color: var(--calcite-ui-foreground-1);
        }
    
    Expand
  2. 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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
        #header-controls {
          display: flex;
          margin-inline-start: auto;
          align-self: center;
        }
    
    Expand
  3. 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.
  4. 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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
        .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.

  1. In the <script> element, below the existing JavaScript code, create a new function to toggle the themes.

  2. Toggle the calcite-theme-dark class on the <body> element. No need to add the calcite-theme-light class, since it is the default.

  3. Access the ArcGIS JavaScript API's light and dark stylesheets using the id attributes you added above.

  4. Negate the disabled attribute on both stylesheets to toggle their boolean values.

  5. Change the basemap between gray-vector and dark-gray-vector depending on the current theme.

  6. 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.
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
    53
    54
    55
    56
    57
    58
    59
    60
    61
    62
    63
    64
    65
    66
    67
    68
    69
    70
    71
    72
    73
    74
    75
    76
    77
    78
    79
    80
    81
    82
    83
    84
    85
    86
    87
    88
    89
    90
    91
    92
    93
    94
    95
    96
    97
    98
    99
    100
    101
    102
    103
    104
    105
    106
    107
    108
    109
    110
    111
    112
    113
    114
    115
    116
    117
    118
    119
    120
    121
    122
    123
    124
    125
    126
    127
    128
    129
    130
    131
    132
    133
    134
    135
    136
    137
    138
    139
    140
    141
    142
    143
    144
    145
    146
    147
    148
    149
    150
    151
    152
    153
    154
    155
    156
    157
    158
    159
    160
    161
    162
    163
    164
    165
    166
    167
    168
    169
    170
    171
    172
    173
    174
    175
    176
    177
    178
    179
    180
    181
    182
    183
    184
    185
    186
    187
    188
    189
    190
    191
    192
    193
    194
    195
    196
    197
    198
    199
    200
    201
    202
    203
    204
    205
    206
    207
    208
    209
    210
    211
    212
    213
    214
    215
    216
    217
    218
    219
    220
    221
    222
    223
    224
    225
    226
    227
    228
    229
    230
    231
    232
    233
    234
    235
    236
    237
    238
    239
    240
    241
    242
    243
    244
    245
    246
    247
    248
    249
    250
    251
    252
    253
    254
    255
    256
            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.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.