Skip to main content

Make a choropleth map, part 1: create a style

One way to show data distribution on a map is with a choropleth, a thematic map in which areas are shaded based on a particular value. In this guide, you will use Mapbox Studio and Mapbox GL JS to make a map of US states showing population density. (If you are familiar with Leaflet, this map may look familiar!)

Getting started

You will be using two Mapbox tools throughout this guide:

  • Mapbox Studio to add your data and create your map style.
  • Mapbox GL JS to add interactivity to your map and publish it on the web.

Download the data

For this guide, you will need to download some data. This GeoJSON file is borrowed from the Leaflet choropleth tutorial and contains data on population density across US states.

arrow-downDownload GeoJSON

Upload your data

To add the population density data to a style in Mapbox Studio, you need to upload it to your account. Go to your Tilesets page in Mapbox Studio to upload your data.

On your Tilesets page, click the New tileset button. Select the file stateData.geojson and upload it to your account.

When the upload is complete, click on the arrow next to the filename to open the Tileset explorer.

Inspect data in the Tileset explorer

When you upload vector data to your Mapbox account, our servers convert it to a vector tileset so it can be rendered quickly and efficiently in the Mapbox Studio style editor and with Mapbox GL JS. The Tileset explorer shows some useful information about the tileset that was created from your uploaded data:

  • Under menu Vector layers, you can see the properties from the original GeoJSON file: density and name. The uploaded tileset maintains the properties from the original data file, which you can use when adding style rules for the tileset.
  • The Tile size graph provides information about the density of data at different zooms.
  • The bounding box viewport provides a visual overview of the geographic extent of your dataset, as well as the bounds of the current map view.
  • Click the Share & use menu to find the tileset ID. You can also toggle the tileset's visibility from Private to Public.

Create a new style

After you've inspected your data, it's time to create a new style so you can put it on the map! Go to your Styles page. Click the New style button. Find the Basic Template style and click Customize Basic Template.

Excellent! Welcome to the Mapbox Studio style editor. This is where you will create your map style.

Rename the style so that you can find it later. Click into the title field in the upper left side of the screen to change the title from Basic Template to Population.

If this is your first time in the style editor, read the Mapbox Studio Manual for more information on getting started.

Add a new layer

To add and style the population density data, you will need to add a new layer to the map:

  1. If the styling panel is displaying the Components tab, toggle to the Layers tab.
  2. At the top of the layer panel, click the + button to add a custom layer.

The editor is now showing your map in x-ray mode. X-ray mode shows all the data in the sources added to the style, regardless of whether there is a layer to style it.

In the New layer panel, look in the list of Data sources for the statedata source. Click the tileset and then select the source layer as the source for this new style layer.

The default Basic map view is not centered on the United States. Mapbox Studio recognizes that the data you have uploaded is focused on a different location, so it displays the message "This tileset isn't available from your map view." Click Go to data, and the map view will refocus on the United States.

Your new layer will be highlighted on the x-ray map.

Click the Style tab and the map will switch back to style mode displaying your new layer. You will see the state data on the map with a default style (black with 100% opacity).

You can rename a layer by clicking on the name of the layer at the top of the panel. Rename your new layer statedata.

Style the layer

On the original Leaflet map, the data is styled based on the population density of each state:

Data-driven styling

In the Mapbox Studio style editor, you can assign a color to each state based on its population density. Click the Style link in the statedata layer. Next, click Style across data range.

Under Choose a numeric data field, select density since you want to style each state according to its population density.

The rate of change is linear. Click Edit and select Step instead. Click Done. Since you have set the rate of change to step, the colors for each range of density between stops will be uniform.

Now it's time to start adding stops and colors! You will create several stops to break states up into groups with similar population densities. Click on Edit in the first density stop. The first stop is fixed at 1.264, based on the information in the data set you uploaded. Click on it and change the color to #FFEDA0. Click Done.

Change density of the next stop to 10, and change the color to #FFEDA0 as well. Click Done.

Click + Add another stop. Change density to 20, and change the color to #FED976. Click Done.

Create the following additional stops:

  • 50: #FEB24C
  • 100: #FD8D3C
  • 200: #FC4E2A
  • 500: #E31A1C
  • 1000: #BD0026

As you start adding stops, you will see the map change on the right to reflect the new stops. In this case, all states with a population density between 0-10 will be assigned the color #FFEDA0, all states with population density from 10-20 will be assigned the color #FED976, and so on.

Give your states a fancy outline style and reduce their opacity to help your readers distinguish between neighboring states. Change the Opacity to 0.6. Next, change the 1px stroke style property to #FFF.

Put labels on top of data

After you've created and styled your layer, your map should look something like this:

Everything looks good, except for one thing - the labels are under the data layer! One of the coolest things about the Mapbox Studio style editor is that you can reorder layers on the map. This means you can put labels on top of your data.

Hover over your statedata layer. Click the menu next to the layer's name in the layer list on the far left and drag your layer below the Place labels, place labels group of layers.

Now that labels are on top of the population density data, city labels are popping out above the more important state labels. To turn off the city labels, adjust the component properties for the Place labels component:

  1. Switch back to the Components tab.
  2. Click on the Place labels component.
  3. Toggle Settlements off.
  4. Toggle Settlement subdivisions off.

Publish the style

Now that you have your map looking good, it's time to publish! Click the Publish button in the top right of the screen, then click Publish again on the next prompt.

Hooray! Your style is now published! If you go back to your Styles page, you will see your new style at the top of the list.

Next steps

Head to part 2 to learn how add interactive elements to your map and publish it to the web with Mapbox GL JS.

Was this page helpful?