Add a line or bar chart to your map.
Maps are a great tool for visualizing data, but sometimes it is difficult to present a complete analysis using only a map. One solution is to add a chart to your map. Bar graphs, trendlines, pie charts and other formats can be useful for comparing data values across geographical regions, over time, or against other variables to help users understand patterns and trends in data.
There are many types of charts and various ways to approach building custom charts. This tutorial explores a simplified example of using a line or bar chart (using the C3 library) that uses data uploaded to Mapbox Studio. The chart is connected to the map so that when someone clicks on a location in the map, the chart will update. The steps of the tutorial focus on how to configure the template code file to edit the chart component.
The map itself is prepared in Mapbox Studio using data that has already combined geometries (e.g. state boundaries) and tabular data (e.g. population counts) - if you have tabular data and need to join it to geometries, explore the Data Joins impact tool.
There are a few resources you'll need to get started:
Tools we'll use:
After you've uploaded your data, it's time to create a new style! Go to your Styles page. Click the New style button and create a new style with your custom data.
For more information on how to style data in the Studio editor read:
This tutorial uses the following public style:
Follow these steps to copy this style to your account.
Download the template from the GitHub repository. Unzip the folder. In the 'charts' folder, you will see:
index.js: This is the main file you will be working in. This contains the configuration code for the template.
index.html: This contains the HTML and some CSS styling rules from Assembly.css for the template.
Note: You can open this file in your browser to see your progress as you edit your code - or use a local server option like the ‘Go Live’ function in VSCode. The template is also configured with a local live-reload development server which you can start by running
npm install and then
npm start in your terminal, then loading HTTP://localhost:8080 in a web browser. The page will automatically refresh as you make changes to your files.
Package.json, package-lock.json: These files contains information about the project, and configuration settings for the development server
main.css: This file contains some CSS styling, and can be used to add additional styles to the application as needed
Set up your app by making some small edits to the index.js file, using your text editor.
Without an access token, the rest of the code will not work.
Note: We recommend using the URL restriction feature on the token to avoid token misuse and want to emphasize that only public tokens should be posted to public repositories. You can find out more information about how to securely manage your access tokens here.
Add your access token into the code, here:
Add the style that you created to your map by replacing the mapStyle URL with the URL of your map style.
You can find the style URL on your Styles page in Mapbox Studio. Click on the menu next to a style to reveal its style URL. Click the icon to copy the style URL.
A source layer is an individual layer of data within a vector source. A vector source can have multiple layers. The source layer for this template is the layer that contains that data to be displayed in the chart.
There are a few places you can find the name of a source layer:
- In the
source-layer propertyof a map's style document.
- In the Mapbox Studio tileset information page for a specific tileset.
- In the Mapbox Studio style editor using the Select data tab.
- In the Mapbox Studio style editor using the Layer overview option in the top toolbar's Settings tab.
In the sourceLayer config option, replace
hist-pres-election-county with your source layer name.
In the title config option, replace
Voting Trends 2004-2016 with your chart title. This replaces the title text for both the sidebar and the webpage itself.
title: 'Voting Trends 2004-2016',
In the description config option, replace the default text with a description of your map and/or chart.
description: 'This map shows estimated voter turnout as a percentage of total population in 2016, select a county to visualize historical data',
In the fields config option add the field names from your data source that you would like to display in the chart. The application will query data from each field, in order, to display on the chart. Field names are case sensitive.
fields: [ '2004_tot_vote_pop', '2008_tot_vote_pop', '2012_tot_vote_pop', '2016_tot_vote_pop', ],
In the labels config option add an x-axis label for each data field that you added in the previous step.
labels: ['2004', '2008', '2012', '2016'],
In the placeNameField config option, replace ‘name’ with the name of the data field that contains geographic information such as ‘state’ or ‘county’ name. This field will be added to your chart so users can view location information when they click the map.
Add a secondary location name to your chart labels by replacing ‘state_abbrev’ with the name of an attribute field that contains additional geographic information.
For example, the default data displays 'Chittenden County, VT" when Chittenden County is selected on the map.
The summaryType config option controls whether values are added or averaged in the initial summary chart of the entire dataset. Be sure to set it to 'avg' when using ratios or other normalized data such as "cases per square mile" or "Vote Turnout %".
In the dataSeriesLabel config option, edit the chart label by replacing ‘Voter Turnout’ with a description that matches your custom data. In the example, the final chart will read: ‘Voter Turnout in County, State’.
dataSeriesLabel: 'Voter Turnout',
The template includes two ways to add a legend with value stops to your map: auto-generated or manual.
To let the template generate a legend automatically, set
true, and set
studioMapLayer to the name of your map layer in Mapbox Studio. Note: This feature is experimental and only supports fill layers with stops (not linear interpolation).
To set the legend colors and stops manually, set
legendColors to an array of colors you’d like to appear using valid CSS color values, and
legendValues to the set of corresponding data values.
The zoomToFeature config option controls whether the map zooms to a feature when clicked. The default option is true. If you want to turn this off, set the value to false.
The highlightColor config option controls the highlight color of clicked features on the map. The default option is ‘#fff’.
This solution supports two chart types ‘line’ or ‘bar’. The default option is set to ‘line’.
You’ve made a web map! But it isn’t a webpage yet… to do that we need some way to host a webpage. There are many different ways to host a webpage. Read this guide to learn how to publish your finished map on GitHub, Netlify, or Glitch.