Make a choropleth map with Mapbox part 1: create a style with Mapbox Studio

One way to show data distribution on a map is by making a choropleth: a map showing areas that 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.

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 containing population density across US states is borrowed from the Leaflet choropleth tutorial.

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. This can be done through the Tilesets page.

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

When the upload is complete, click on the arrow next to the filename to open up its 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.

  • 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: as vector tiles are made up of vector data, they 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.

Excellent! Welcome to the Mapbox Studio style editor. This is where you will create your map 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.

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.

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

Configure the layer

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

To recreate this style in the Mapbox Studio style editor, you are going to create a separate layer for each group of states. Each layer will also have a data filter, so that the correct states are styled with the correct colors. By the end, you will have eight layers. (Yes, it is totally cool to have more than one layer styling the same source!)

Rename the layer

First, you can see at the top of the panel that this first layer is called statedata. Going in ascending order, click on the title and change it to 0-10.

Filter the data

To make sure this layer only styles states where the population density is less than 10, add a data filter to the layer. At the top of the layer panel, click the Select data tab. This will kick the map back into x-ray mode and will show you your data options. To add a filter:

  • In the Field values section, click + Add filter.
  • There are two properties in the data that you can use to filter: density and name. Click density.
  • From the drop down menu, select is less than.
  • Click Empty and type 10 into the field. You should see the data highlighted on the map reduced to just Montana, North Dakota, and Wyoming.

Click the Style tab in the layer panel to go back to style mode.

Style the layer

Set the layer style to the following to (mostly) match the Leaflet example:

  • Color: #FFEDA0
  • Opacity: 0.6
  • 1px stroke: rgba(0, 0, 0, 0)

Duplicate the layer

Each group of states in the original example will need its own layer. Fortunately, duplicating layers in the Mapbox Studio style editor is a snap!

To duplicate the 0-10 layer, make sure it is highlighted in the layer list and click the button at the top of the layer list panel.

When you duplicate the 0-10 layer, the new layer will be called 0-10 copy and will have all the same styling rules and the same data filter. This is handy for things like opacity, but the color and data filter will have to be changed for each new layer.

Create a new layer for each group of states using the following colors:

  • 0-10: #FFEDA0 (this one is already done!)
  • 10-20: #FED976
  • 20-50: #FEB24C
  • 50-100: #FD8D3C
  • 100-200: #FC4E2A
  • 200-500: #E31A1C
  • 500-1000: #BD0026
  • 1000+: #800026

Make some final tweaks

After you’ve created all of your layers, your map should look something like this:

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.

Move your layers below the labels

To make this process easier, you can add all of the layers you just created to a group. Select the layers in the menu and click the . You can select multiple layers at once by holding down command (Mac) or CTRL (Windows) while clicking to select layers. Click the pen to edit the name of the group.

Now that the layers are in a group, you can drag them below the labels. Boom! Labels on top of the map!

Turn off 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 Place labels group in the layer list and click the button to turn these layers off.

Show water and administrative boundaries

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

Change style of state labels

The default state label layer works really well with a grayscale background, but they disappear on top of the population density data. To make them pop, add a white halo around the text.

Publish the style

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

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.

Next article:

Make a choropleth map with Mapbox part 2: publish your style with Mapbox GL JS

Additional questions? Ask our support team or learn more about How Mapbox Works.