Customizing theme colors in Map Journal and Map Series

Owen Evans
Mar 3, 2017 · 4 min read

The March 2017 update to ArcGIS Online includes a new feature called Shared Themes that lets an administrator set a logo and a palette of colors that can be used to apply consistent branding to web apps created by members of the organization.

For Story Map Series and Story Map Journal, the organization’s shared theme colors are used to generate an Organization Theme that is shown with the other theme options in builder.

Having an administrator configure a shared theme for your organization is the best way for most story map authors to apply branding to their stories; however, some authors may want to apply their organization’s theme colors in a different way or personalize the theme colors for individual stories.

Before the March 2017 update, the only way to use custom colors for a Map Series or Map Journal story was to download the app from GitHub, modify the code, and host the app yourself. But, as part of the work to support shared themes in these apps, the theme color values are now exposed as properties in the story configuration JSON. This means you can now specify theme colors for Map Series and Map Journal stories hosted on ArcGIS Online by editing the story JSON using a tool like ArcGIS Online Assistant.

WARNING #1 — Editing JSON can break your story!

If you’ve never edited story map JSON before it’s wise to first try it a few times on a test story until you’re comfortable with the procedure. If you choose to edit JSON for a published story, be aware of the risk you are taking and be sure to copy and save its original JSON in a text file in case something goes wrong.

WARNING #2If you’re not a web designer (or working with one) we strongly recommend you stick with one of the themes provided.

Here’s an example of the JSON that stores the theme for your story. The parameters you see will depend on the story type and layout (Map Series tabbed layout, Map Journal floating panel layout, etc.).

      "theme": {
"colors": {
"name": "side-default-1",
"themeMajor": "white",
"dotNav": "#777777",
"panel": "#FFFFFF",
"media": "#EEEEEE",
"text": "#000000",
"textLink": "#555",
"softText": "#c0c0c0",
"softBtn": "#444",
"esriLogo": "black"

To set theme colors for your story…

  1. At the top click I want to…View an item’s JSON.
  2. In the left panel, find the story map you want to customize. These instructions are for Map Journal and Map Series stories only.
  3. In the Data section of the right panel, look for theme in the JSON (as shown above). As mentioned above in warning #1, now is a good time to Copy the original JSON and save it in a text file in case something goes awry. If you don’t see the theme, see the note at the end of this post.
  4. Click Edit (the pencil button) to start editing the JSON.
  5. Append -modified to the name property of the theme. We recommend you do not edit the name in any other way.
  6. Edit the properties of the theme as you like using any valid color specification method like hex color codes, HTML color names, or RBGa values (if you need transparency).
  7. Use the Save button at the top of the Data section to save your changes.
  8. View your story or open it in builder (if it’s already open, reload the page) to see your shiny new theme colors!

Here are some general notes and tips for configuring theme properties:

  • You can adjust the transparency of the floating panel in Map Journal using the panelOpa property. If panelOpa is not set, the floating panel will be 80% opaque.
  • You can adjust the transparency of the description panel in Map Series (tabbed or bulleted layout only) by using an RGBa color value.
  • themeMajor can be white or black and controls the appearance of some minor visual elements like the arrows in the legend header and dot navigation strip.
  • Since you are likely using your own logo if you are customizing theme colors you can ignore esriLogo and esriLogoMobile.

You’ve edited the theme, now what?

At this point, if you choose a theme other than Current Theme and save the story, your modified theme will not be available next time you load the story in builder. You’ll need to use the procedure above to edit the theme colors again.

Additional themes in Map Journal.

What if you don’t see JSON for the theme?

Story Maps Developers' Corner

Learn best practices, read quick tips, and discover new ways to make your story map stand out from the crowd. Start creating your story at:

Owen Evans

Written by

Product Engineer on Esri's Story Maps Development Team.

Story Maps Developers' Corner

Learn best practices, read quick tips, and discover new ways to make your story map stand out from the crowd. Start creating your story at:

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade