Interactive Storytelling with Mapbox & Tableau
Interactive Storytelling with Mapbox & Tableau

Interactive Storytelling with Mapbox & Tableau

I recently watched a webinar hosted by Jonni Walker (Tableau)  Allan Walker (Mapbox) and Melissa Pavlik (ACLED) which looked at customising mapbox maps and also how to use the Interactive Storytelling feature of mapbox to build a ‘scrollytelling’ story using a template provided by mapbox.

I decided to have a go at creating an interactive storytelling example myself and the following are the steps I used.


You will need:

This data was used to create a dataset and tileset in mapbox which are then used in the storytelling template.


So, to get started, you simply go to the following link and follow the steps there:


I am copying the steps from the github page and adding some of my own notes and understanding in red below:


Getting Started

  • Download this repository as a ZIP file using the button above, and unzip it. If you are using git, clone this repository.
  • If you are new to coding in JavaScript, follow the instructions for Vanilla JS. If you are already working with React, are comfortable with the command line and build systems, and/or want bundled and minified code, choose React.

Vanilla JS

In your local copy of this repository (the unzipped file you downloaded), navigate to the src/vanilla-js/ directory.

Make a copy of config.js.template and name it config.js. Open the new config.js file in your text editor.

All really simple so far.

Steps to creating your interactive story with Mapbox & Tableau

1.Select the map style you want to use (the default is Mapbox Streets, but you can find more here, or use one of your custom Studio styles). 

If you have created a mapbox map style, simply copy the style URL as seen in the image below below. You can also take the access token for step 2 from the image below

2.Add a Mapbox access token. A good practice is to create a separate token per map to be able to track traffic to your different maps.

3.Choose whether or not to display a marker at the center of each map location. 

4.Choose a theme for the story text. There are light and dark options.

5.Choose where your story should be aligned over the map. Options are center, left, right.

In your text editor, simply amend the section if required, as below:

6.Add as many chapters in your template as needed. You’ll need a , between each section, but no comma at the end. Here is what a chapter looks like:

7.Fill out your sections as needed. Give each section a unique name in the section id property. This will become the HTML div id, so avoid spaces in the name. The title, description properties are optional. The description supports HTML tags. If you have an image that goes with that section of the story, add the path to the image in the image property.

I used png images taken from Tableau desktop that are related to the map section in each chapter but admittedly, they are a little small and hard to read but you get the idea. These are saved to my github page and the links are just copied into the config.js file.

8. For location, you can use the helper.html file to help you determine the map’s position. This tool prints the location settings of the map on the screen in a format ready for copy/paste into the template.

This bit is really cool as you can place the map exactly where you want with the helper.html file downloaded from the github page earlier. Double click it and open it. You can navigate to any location and amend the zoom, pitch and bearing as well as the lat and long. When you are happy with the way the map looks, you can copy and paste the lat, long, zoom, pitch and bearing directly into the text editor.

9.Repeat until you have the location entered for each of your sections.

10. Open index.html in a browser, and scroll. Voila!


Now you can scroll through the story as you like, up and down and watch the maps change and the text follow along.


To add some more detail, like data points in the water events data set, I created a dataset in mapbox, again very simple, as below:

Create new dataset and then select upload. I used a csv here.

I then created a tileset from this dataset by going to the Tilesets menu, selecting New Tileset, as below:

I chose to create my tileset from my recently created dataset, as seen below:

This will create a new tileset that you can add to your map style within mapbox studio, as below:

The newly create tileset is now available to add within the ‘add new layer’ menu as seen above.

Now we have our storytelling template created, we can save both the config.js and the index.html files to github and then embed them into a Webpage object in a Tableau dashboard.

I had to check with Allan Walker from mapbox on the syntax for the URL which is below for my map template:

To create a Webpage object in Tableau, simply create a new dashboard, drag in a new Wepgae object, as below:

Paste your URL to your index.html in and voila;

Make sure to set the size to automatic so it fits the full screen it has available on the viewers device (mobile isn’t great in this template but we are only getting started).

The map isn’t showing I hear you shout!

It will display when you publish the workbook to Tableau public or your server, as below:

Now scroll away and watch the story unfold.

The link to my example is here:!/vizhome/samplewater/Dashboard1

Happy scrolling storytellers!


Who/What is…?

The Information Lab Ireland

The Information Lab (“TIL”) is a Gold resale partner of Tableau and Alteryx and offers related consulting and training across seven territories in Europe. TIL has offices in Ireland, the UK, Germany, France, Italy, the Netherlands and Luxembourg.

Clients include Coca-Cola, Close Bros Bank, PepsiCo, Deloitte, UBS, Solar Turbines & Boston Consulting Group. The Information Lab has worked with Close Brothers Bank to support their use of Alteryx for compliance with IFRS 9.

The Information Lab Ireland is at the forefront of creating a data-driven culture in Ireland. As part of its vision, The Information Lab Ireland regularly hosts free events throughout the country to show how being data-driven can improve decision making and lead to a better understanding of the world around us.

For more on these events please like us on Facebook or follow us on Twitter


Tableau is the gold standard for intuitive, interactive visual analytics and an established enterprise platform. Over 54,000 customers have adopted Tableau to answer more questions of their data.