Dynamic charts

Add a line or bar chart to your map.

View fullscreen demo

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:

Templates:

• Sample code
• Example style
• Sample tileset ID: mapbox-community.hist-pres-election-county
• Live map demo

Tools we'll use:

• Mapbox account to access: ‍‍‍

  Mapbox Studio to create your map style.

  Mapbox GL JS to add interactivity to your map and publish it on the web‍‍.

• C3 charts to add a line or bar chart to the map

Upload your custom data to Mapbox Studio as a tileset. You can upload your data through:

• The Mapbox Studio style editor
• Your tilesets page in Mapbox Studio
• The Mapbox Tiling Service
• The Mapbox Uploads API

Read more about uploading data into Mapbox.

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:

Make a choropleth map, part 1: create a style

This tutorial uses the following public style:

https://api.mapbox.com/styles/v1/mapbox-community/ckglghzgg0d6y19pe11eo9zlw.html?title=copy&access_token=pk.eyJ1IjoibWFwYm94LWNvbW11bml0eSIsImEiOiJja3N0Y3VjcHcxNDdiMndvMzk4bmwyZmN5In0.1-SawzsXOmK9qtUD2y13kg&zoomwheel=true&fresh=true#2.39/51.25/-115.5

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.‍

Login or create a free Mapbox account. Find your access token on your Access tokens page or the main page you sign into your Mapbox account.

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. Find out more information about how to securely manage your access tokens.

Add your access token into the code, here:

 accessToken: 'pk.eyJ1IjoibWFwYm94LWNvbW11bml0eSIsImEiOiJja2tkN21jcjAwMG51MnBxdHAxemdueGpzIn0.e0IzLkytGq4pcGGieP8KNA',

Add the style that you created to your map by replacing the mapStyle URL with the URL of your map style.

 mapStyle: 'mapbox://styles/mapbox-community/ckglghzgg0d6y19pe11eo9zlw',

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 property of 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.

  sourceLayer: 'hist-pres-election-county',

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.

 placeNameField: 'name',

Optional:

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.

placeAdminField: 'state_abbrev',

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 %".

summaryType: 'avg',

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 autoLegend to 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.

zoomToFeature: true;

The highlightColor config option controls the highlight color of clicked features on the map. The default option is ‘#fff’.

highlightColor: '#fff',

This solution supports two chart types ‘line’ or ‘bar’. The default option is set to ‘line’.

chartType: '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.

View our finished example map at https://labs.mapbox.com/impact-tools/charts/.

Need more help? Ask questions on Stack Overflow or contact Mapbox Support. If you are working on a social good project, contact the Mapbox Community Team.

Want to share what you’ve built? Tweet it with #builtwithmapbox