Skip to main content

Use Boundaries v4 on a map

Additional Developer Resources

Mapbox Boundaries can be added to maps and used to create visualizations in any Mapbox GL-supported product, including Mapbox Studio, Mapbox GL JS, and the Maps SDKs for iOS and Android. The following examples use Mapbox GL JS.

It is recommended to first read the Mapbox Boundaries reference if this is your first time building with the product.

Basic example​

To add Mapbox Boundaries to a Mapbox GL JS map, start with the 'add a vector tile source' example and add one of the Boundaries tilesets as a source. The source is added with promoteId to use the mapbox_id property of each feature as the unique identifier in the source.

Migrating from v3
Using promoteId while adding any Boundaries vector tiles sources is required due to breaking changes to IDs introduced in v4. Not using promoteId causes data joins and feature state interactions to fail.See the migration guide for additional information.

Then, add a styling layer to the map with this data source filtered by an appropriate worldview filter to remove overlapping boundaries in disputed areas.

For example, to add the first-level administrative division boundaries, we would use the admin-1 level tileset. A worldviewFilter variable is used to define a Mapbox GL filter to only render features from the "all" or "US" worldviews.

This creates a map style with Mapbox Boundaries that's ready to have custom data joined into it.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>Use Boundaries v4 on a map</title>
<meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no">
<link href="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.css" rel="stylesheet">
<script src="https://api.mapbox.com/mapbox-gl-js/v3.5.1/mapbox-gl.js"></script>
<style>
body { margin: 0; padding: 0; }
#map { position: absolute; top: 0; bottom: 0; width: 100%; }
</style>
</head>
<body>
<div id="map"></div>
<script>
	// TO MAKE THE MAP APPEAR YOU MUST
	// ADD YOUR ACCESS TOKEN FROM
	// https://account.mapbox.com
	mapboxgl.accessToken = 'YOUR_MAPBOX_ACCESS_TOKEN';
  const map = new mapboxgl.Map({
    // Choose from Mapbox's core styles, or make your own style with Mapbox Studio
    style: 'mapbox://styles/mapbox/light-v11',
    bounds: [
      [-128.27108, 24.75835],
      [-65.14635, 49.76109]
    ],
    container: 'map',
    antialias: true
  });

  map.on('load', function () {
    // Add a vector source for admin-1 boundaries
    map.addSource('admin-1', {
      type: 'vector',
      url: 'mapbox://mapbox.boundaries-adm1-v4',
      promoteId: 'mapbox_id'
    });

    // Define a filter for US worldview boundaries
    let worldviewFilter = [
      'any',
      ['==', 'all', ['get', 'worldview']],
      ['in', 'US', ['get', 'worldview']]
    ];

    // Add a style layer with the admin-1 source below map labels
    map.addLayer(
      {
        id: 'admin-1-fill',
        type: 'line',
        source: 'admin-1',
        'source-layer': 'boundaries_admin_1',
        filter: worldviewFilter
      },
      // This final argument indicates that we want to add the Boundaries layer
      // before the `waterway-label` layer that is in the map from the Mapbox
      // Light style. This ensures the admin polygons are rendered below any labels
      'waterway-label'
    );
  });
</script>

</body>
</html>
Additional Developer Resources
Was this page helpful?