Interactive Storytelling

A low-code template to help you tell your map-based story

What does this solution do?

While newsrooms have dedicated development resources to build the beautiful interactive maps they feature, we want to make it easy for anyone to tell their stories with a map. The Mapbox Storytelling Template provides a low-code, modularized template that anyone can use to input copy, select the elements of the map that they want to feature for each “chapter,” and quickly publish a highly interactive story experience with high quality visuals to support the content.

The template works well for any story that highlights multiple locations, and especially ones that include custom map data. For example, in a story about the changing size of glaciers, maps of the glaciers at different points in time display alongside the text describing those changes.

Use it to compare demographic data in different cities, share reports about factory site output, highlight housing market trends, communicate interactive travel itineraries, maybe display migratory patterns; the template allows easy output and publication of these datasets using the rich, interactive and compelling canvas of a map. Try the example below for yourself.

Last Updated:
Start building
Source code on Github

Solution Details

The template contains two files:

  • A story content file (config.js). This JSON-formatted text file includes story copy, location information, and settings to control how the map & story are displayed. This is what the storyteller edits.
  • A map story file (index.html). This HTML file reads information from the content file and dynamically builds out the story and map controls. This is what the reader sees.

Once the content file is set up, these two files are published together to a static web-hosting location.

Story content file

Think of a story as a set of data and the content file as a template for how the data is structured. The storyteller takes the story elements and puts them into the defined structure, enabling the code in the index.html file to read the data and bring the story to life.

The content file has general settings like horizontal alignment (left, right, or center), light or dark theme for the page, and which map to use. It also has settings for each location in the story, including a photo, description, and coordinates. If you have set up custom map data in Mapbox Studio, there are also settings to control which map layers to show and hide.

Map story file

The map story file does not have to be edited. It already contains the basic HTML structure, the CSS properties that define the style and layout, and the JavaScript code that dynamically builds the page based on information in the config.js file.

If the user has CSS knowledge and wants to customize the map story file, its simple structure makes it easy to enhance. You can change the theme colors and adjust the layout, spacing, and look of the story.

We also built an HTML page to help find location coordinates and set up the best "camera angle" to showcase a location. Find the helper page here.

Technical Information

Things you need to get started:

  • a Mapbox access token. Sign-up for a free account here.
  • a text editor. Atom, Sublime Text, and VS Code are common options.
  • a place to host your story files. Any web-accessible location will work, like a web server, S3 bucket, or service like Netlify. Github pages, Glitch, and are fine options, too.

Mapbox usage:

Every view on your story triggers a "map load". Mapbox has a generous free tier (up to 50,000 map loads per month). For more pricing details, consult the Mapbox pricing documentation.

Additional resources

Access the tutorial and template code here.

Access the Interactive Storytelling webinar here.

Now compatible with 3D terrain.

Ready to get started?

Create an account or talk to one of our experts.