Leaflet Storymaps with Google Sheets

TODO: Add intro text; mention (but not recommend)Knight Lab’s StoryMap and ESRI Story Maps because users cannot easily migrate data out

Try it: Explore the map or right-click to view full-screen map in a new tab

The map pulls the point data and settings from a linked Google Sheet, which you can explore below or right-click to view full-screen Sheet in a new tab


  • Show map points, text, images, and links with scrolling narrative
  • Free and open-source code template, built on Leaflet and linked to Google Sheets
  • Fork the code and host your live map on the web for free with GitHub Pages
  • Geocode location data with US Census or Google, using script inside the Google Sheet
  • Easy-to-modify data and map options in Google Sheet tabs or uploaded CSV files
  • Responsive design resizes your maps to display inside most mobile devices

Create Your Own

    1. Fork (copy) the code template and publish your version with GitHub Pages
    1. File > Make a Copy of Google Sheet template, Share, and File > Publish
    1. Paste your Google Sheet URL in two places in your GitHub repo
  • C2) NEW: Create a free Google Sheets API key to paste into the code
    1. Modify your map settings in the Options tab and test your live map
    1. Geocode locations in the Points tab

To solve problems, see the Fix Common Mistakes section of the appendix.

A) Fork (copy) the code template and publish your version with GitHub Pages

Before you begin, this tutorial assumes that you:

  1. Right-click to open this GitHub code template in a new tab: https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets

  2. In the upper-right corner of the code template, sign in to your free GitHub account

  3. In the upper-right corner, click Fork to copy the template (also called a code repository, or repo) into your own account. The web address (URL) of the new copy in your account will follow this format:


Reminder: You can only fork a GitHub repo one time. If needed, see how to make a second copy in the Create a New Repo in GitHub chapter in this book.

  1. In your new copy of the code repo, click on Settings, scroll down to the GitHub Pages area, select Main, and Save. This publishes your code to a live map on a public website that you control.

  2. Scroll down to GitHub Pages section again, and copy the link to your published web site, which will follow this format:

  1. Scroll up to the top, and click on your repo name to go back to its main page.

  2. At the top level of your repo main page, click on README.md, and click the pencil icon to edit this file, written in easy-to-read Markdown code.

  3. Delete the link to the current live site, and paste in the link to YOUR site. Scroll down and Commit to save your edits.

  4. On your repo main page, right-click the link to your live map to open in a new tab. Be patient during busy periods on GitHub, when your website may take up to 1 minute to appear the first time.

B) File > Make a Copy of Google Sheet template, Share, and File > Publish

  1. Right-click to open this Google Sheets template in a new tab: https://docs.google.com/spreadsheets/d/1AO6XHL_0JafWZF4KEejkdDNqfuZWUk3SlNlQ6MjlRFM/

  2. Sign into your Google account

  3. File > Make a Copy of the Google Sheet template to your Google Drive

  4. Click the blue Share button, click Advanced, click to change Private to Anyone with the link > Can View the Sheet. This will make your public data easier to view in your map.

  5. File > Publish the Link to your Google Sheet to the public web, so the Leaflet map code can read it.

Screenshot: File > Publish the link to your Google Sheet

  1. At the top of your browser, copy your Google Sheet web address or URL (which usually ends in ...XYZ/edit#gid=0). Do NOT copy the published URL (which usually ends in ...XYZ/pubhtml).

Screenshot: Copy the Google Sheet URL, not the Publish URL

C) Paste your Google Sheet URL in two places in your GitHub repo

  1. First, connect your Google Sheet directly to your Leaflet Map code. In your Github code repo, click to open this file: google-doc-url.js

  2. Click the pencil symbol to edit the file.

  3. Paste your Google Sheet URL into the code to replace the current URL. Do not delete the single-quotation marks or semicolon.

  4. Scroll to bottom of page and press Commit to save your changes. Now the Leaflet Map code can locate your published Google Sheet.

  5. Next, let’s paste your Google Sheet URL in a second place to keep track of it. Go to the README.md file in your GitHub repo, click to open and edit, and paste your Google Sheet web address to replace the existing link near the top. Commit to save your changes.

D) Modify your map settings in the Options tab and test your live map

In the top-level of your GitHub repo, test the new links to your map and your Google Sheet to make sure they work and point to your versions.

** TO DO - redo GIF **

In your linked Google Sheet, go to the Options Tab and modify these items:

  1. Map Title – insert your own title

  2. Map Subtitle – insert your own version

  3. Author Name – insert your own name, or first name, or initials (will be public)

  4. Author Email or Website – insert your own (will be public), or delete the current name to make it blank

Open the link to your live map in a new browser tab and refresh to see your changes.

E) Geocode locations and customize new markers in the Points tab

In your new map, our next goal is to add and modify the appearance of a new set of point markers, based on new addresses that you will enter and geocode.

In the Points tab of your Google Sheet:

  1. Do NOT delete or rename any column headers. However, you have the option to add new column headers to display in your map table.

  2. Geocode your new data inside your Google Sheet by dragging your cursor to select 6 columns of data: Location - Latitude - Longitude - Found - Quality - Source

  3. In the Geocoder menu that appears in this Google Sheet template, select one of the geocoding services. If one service cannot locate your data, try the other. Always inspect the accuracy of the Found column.

Open the link to your live map in a new browser tab and refresh to see your changes. If your new markers appear correctly, then delete the existing rows that came with this template.


Add documentation for new features added in 2020

Add links to your text in the Google Sheet

Add line breaks to your text in the Google Sheet

TODO to code: Add Scroll Down text and symbol after the subtitle


I added a new column to the Chapter tab called “Marker”. It has a dropdown with currently three options: Numerated (defaults to that, even if empty value), Plain (with no number), and No marker. The latter is what you want. It can be potentially extended to colours, types of markers, etc. https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L121-L131

Overlay GeoJSONs

I added two columns, GeoJSON Overlay with the URL to the GeoJSON, and GeoJSON Feature Properties, which is CSS that defines style of features. List the styles separated by semicolon, and no quotation marks required. Eg fillColor: orange; weight:2, opacity: 0.5, color: red, fillOpacity: 0.1 In the code, you will see two vertical lines: they mean “or”. If the value of the left-most expression is not undefined, it uses it. If not, it keeps moving to the right until there is a value that is not an empty string. For example, https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L310 color: feature.properties.COLOR || props.color || ‘silver’,

Will first attempt to extract the color from the COLOR property of each geoJson feature (useful for choropleth). If not found, it tries the GeoJSON Feature Properties “color”. If that is not set, it uses silver. https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L288-L316

Data in local CSV files

If googleDocURL variable does not exist (eg you delete the file) or is an empty string, it reads two spreadsheets: Options.csv and Chapters.csv from the /csv folder. Otherwise, it reads from the google sheet. https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L13-L35 When data is read from a .CSV, it links that in the attribution (https://github.com/handsondataviz/leaflet-storymaps-with-google-sheets/blob/master/scripts/storymap.js#L393-L396)

Modify your Style Sheet

To adjust title size: In GitHub, go to css/styles.css file, scroll all the way to the bottom, and adjust font-size values (or just use the links below). See your title around line 170, and change font-size up or down….

To add a horizontal line, you need to be a bit creative (see screenshot attached)! Break down text in your Description with the following code for the horizontal line:

<span style="display:block;width:100%;height:1px;background-color: silver; margin: 20px 0;"></span>

When you copy-paste this snippet, the straight quotation marks do not turn into curly marks, otherwise it won’t work.

Learn more: To solve problems, see Fix Common Mistakes section of the appendix.