Customize the theme and fonts in Cascade

Published in

Classic Esri Story Maps Developers' Corner

4 min readJun 28, 2017

The June 2017 release of Story Map Cascade has a new dark theme and font options for the titles and body text in your story.

Theme and font options are available in the June 2017 release of Cascade

These new features open up some additional opportunities for those of you that like to dabble in story map customization. As shown below, there are some new parameters in the story JSON that are available for you to edit.

"settings": {
      "theme": {
        "colors": {
          "id": "black-on-white-1",
          "label": "Light",
          "themeMajor": "light",
          "themeContrast": "dark",
          "bgMain": "white",
          "textMain": "#4c4c4c",
          "selected": true
        },
        "fonts": {
          "titleFont": {
            "label": "Open Sans",
            "fontFamily": "'open_sans', 'Helvetica Neue', 'Helvetica', 'Arial', sans-serif"
          },
          "bodyFont": {
            "label": "Noto Serif",
            "fontFamily": "'noto_serif', 'Georgia', 'Hoefler Text', 'Palatino', cursive"
          }
        }
      },

Great Power | Great Responsibility

Often your goal as a storyteller is to create an informative story that your readers will enjoy, and how your story looks is a big part of how successful it will be. Be sure to make good choices if you choose to make significant modifications to your story’s appearance.

If you’re not someone who has good design sense (be honest!), we recommend you consult with a designer to help you pick your theme colors and fonts. This will guard against poor choices that can make your story difficult to read or enjoy. Often organizations have standard colors and fonts that are approved for web content, and a designer can help you understand where to get more information about this.

If you’ve never edited the JSON for a story map, be sure to read the article below. It details the risks of, and best practices for, manually modifying the content, structure, and configuration of a story map. Once you’re comfortable with the process, read on!

Editing the configuration of a story map

Using the ArcGIS Online Assistant to edit a story map’s JSON

developerscorner.storymaps.arcgis.com

Theme

To change the theme colors of your story you can use ArcGIS Online Assistant to edit the story JSON as described below.

Edit bgMain to provide the background color in any valid color format.
Edit textMain to provide the text color.
If your background color is a light color set themeMajor to light. If it’s a dark color make it dark.
Make themeContrast the opposite of themeMajor, either light or dark.
It’s not required, but it’s a good idea to change the id parameter to something like my-theme so you can identify a story for which you’ve customized the theme.

NOTE: If you don’t the properties mentioned above, choose a different theme in builder and save your story. That will write the parameters to the JSON so you can edit them.

The themeMajor and themeContrast parameters control certain elements of your story (like link color) and the builder user interface, so be sure to set these properly.

Fonts

If you want to use a different font in your Cascade story (that is, other than the four fonts available to choose from in builder), you’ll need to download the app and host it on your own web server (unfortunately, we can’t let you link to outside font sources from our hosted apps for security reasons).

To download the app, visit the Cascade page of the Story Maps website and look for the “Host it yourself” section at the bottom of the page. If you’ve never hosted a story map on your own before here’s what you need to know.

Once you download the app and build your story, here are the steps to customize it.

Add a link to an external font stylesheet in the <head> of index.html, ex: <link href="https://fonts.googleapis.com/css?family=Barrio" rel="stylesheet">
Find settings.theme.fonts in the story JSON and change the label and fontFamily of the titleFont and/or bodyFont objects to the desired fonts.

You can specify your own fallbacks in fontFamily or just copy the ones you see. Be sure to read up on web safe fonts before setting any fallbacks.

There are lots of great fonts available on Google Fonts and it’s easy to grab the code you need for the <link> tag.