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

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 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 some useful information about the tileset that was created from your uploaded data.

new 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 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. Under Create a new style, click the Create button next to Basic Template. (To follow along with this tutorial, you need to use the Basic template. If you choose a different template, the options that you see may look slightly different.)

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 basic style

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

Mapbox Studio style editor showing how to rename a 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 + Add layer.

Mapbox Studio add new layer

The editor is now showing your map in x-ray mode. X-ray mode 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, 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.

Mapbox Studio style editor new tileset not available in map view

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

Mapbox Studio set data dialog showing x-ray mode

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

Mapbox Studio state data with default fill-color style

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:

original Leaflet choropleth map

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 to interpolate over a range, select density since you want to style each state according to its population density.

Mapbox Studio style editor interpolate from data

The rate of change is set to 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.

Mapbox Studio style editor set the rate of change to step

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.

Mapbox Studio style editor set the base step color

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

Mapbox Studio style editor set first density stop

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

Mapbox Studio style editor set colors for all density stops

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.

Mapbox Studio style editor 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 looks good, except for one thing - the labels are underneath the data layer! One of the coolest things about the Mapbox Studio style editor is that you can reorder any of the elements of the map. This means you can put labels on top of your data.

Hover over your statedata layer. Click the next to the layer’s name in the layer list on the far left and drag your layer below the place labels.

Mapbox Studio style editor move statedata layer

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, click on Filter layers and type place. This will return all of the city label layers. Select multiple layers at once by holding down command (Mac) or CTRL (Windows) while clicking on these layers. Next, click the button at the top of the layers pane to turn off these layers’ visibility.

hide layers in the Mapbox Studio style editor

To make the boundaries between states more visible, you can move the admin-state-province layer above the statedata layer in the layer list. You may also want to move the water layer.

move 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 on the right side of the screen, then click Publish again on the next prompt.

publish success message

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.