No code
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!)

View finished map.

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.

Upload your data

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

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

click the new tileset button in Mapbox Studio to upload your data

When the upload is complete, click on the arrow next to the filename to open up its information page.

upload dialog leading to your tileset's information page

Inspect the tileset

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 information page shows a bunch of useful information about the tileset that was created from your uploaded data.

state data tileset information page

  • In the center, 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 map ID is the unique identifier for this tileset.
  • Format, Type, Size, and Bounds provide general information about the tileset.
  • Zoom extent tells you the zoom levels at which tiles were generated for your uploaded data. Don’t worry too much about this number. Vector tiles are made up of vector data and can be overzoomed and styled up to zoom level 22.

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 and click the New style button. When prompted to pick a template style, give your map style a title, click Light, and then hit the Create button.

Mapbox Studio create a new style dialog

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

Mapbox studio style editor showing default light style

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

Add a new layer

In order to add and style the population density data, you will need to add a new layer to the map. At the top of the layer panel, click + New layer.

mapbox studio add new layer

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

In the New layer panel, click the Source field to add stateData as the source for this new layer. Once added, this layer will be highlighted on the x-ray map.

mapbox studio set data dialog showing x-ray mode

Click Create layer to add the layer to your style. The map will jump back to style mode and you will see the state data on the map with a default style (black with 100% opacity).

state data with default fill-color style

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

Style the layer

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

original leaflet choropleth map

Property functions

In the Mapbox Studio style editor, you can style each state according to its population density using property functions. To assign a color to each state based on population density, click the Value options link. Then click Set value by data.

enable property functions in the Mapbox Studio style editor

Once you’ve enabled property functions, set the Field to density since you want to style each state according to its population density. Keep the Domain as a number, since the density property is a number. Set the Function type to interval since you will be assigning colors to each state based on specified intervals. Set the Default value to #800026. Don’t change the Zoom level.

mapbox studio property functions

Now it’s time to start adding stops and colors! You’ll create several stops to break states up into groups with similar population densities. Click Add stop to add new stops to the list.

Create the following stops:

  • 10: #FFEDA0
  • 20: #FED976
  • 50: #FEB24C
  • 100: #FD8D3C
  • 200: #FC4E2A
  • 500: #E31A1C
  • 1000: #BD0026

As you start adding stops, you should 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. Any states with a population density outside the set intervals (in this case, over 1000) will be assigned the default value, #800026.

Other style properties

Give your states a fancy outline style and reduce their opacity to help your readers distinguish between neighboring states. Change the Opacity and 1px stroke style properties for the entire layer. Change the Opacity to 0.6 and the 1px stroke to #fff.

change outline and opacity

Reorder your layers

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

screenshot of the choropleth map of the United States with custom data on top of place labels

Everything is looking pretty great, except for one thing: the labels are underneath the data! One of the coolest things about the Mapbox Studio style editor is that you can reorder any of the elements of the map, which means you can put labels on top of your data.

Click the next to the name of your layer statedata in the layer list on the far left and drag your layer below the place labels.

Now that labels are on top of the population density data, less important city labels are popping out above the much more important state labels. To turn off the city labels, select the City labels group in the layer list and click the button to turn these layers off.

To make the boundaries between states more visible, you can move the Administrative boundaries group above the statedata layer in the layer list. You may also want to move the Water layers.

reorder layers in the Mapbox Studio style editor

Publish the style

Now that you’ve got your map looking good, it’s time to publish! Click the Publish style button at the top of the toolbar and click Publish again on the next prompt.

publish success message

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

Next steps

Head to part 2 to learn how to publish your map style and add interaction with Mapbox GL JS.