All impact tools

Data Joins

Add tabular data to a vector tileset using client-side data-joins.

Live interactive demo

When adding custom data to a map, you may find that some of your data exist in a source that is separate from your geospatial data. For example, you might have a table of population data by country but the only spatial information included is the country name. In this case you need a way to ‘join’ the data to geometries, like country boundaries, to be able to visualize them on a map. In some cases, it can be tricky to prepare joined data before adding it to a map, for example, if the data are updating frequently, if the data file is large, or if you can’t directly edit the geometries source that you want to use (like a Mapbox Boundaries tileset).

Using a ‘client-side data-join’ lets you combine vector tile geometries with other data dynamically when your web map loads. In this tutorial, you will learn how to use the Feature State method to join a vector tile to an external data file, and then use data-driven style notation to visualize the data.

Access the tutorial and template code here.

Maps built like this

View our finished example map at

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