Use Boundaries in a map

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.

Basic example

To add Mapbox Boundaries to a Mapbox GL JS map, use map.addSource to add a Boundaries tileset to the map, then use map.addLayer to apply a style to the data. Here is an example adding the admin-1 polygon tileset and styling it with a basic fill.

map.on('load', function() {

  // Add source for admin-1 Boundaries
  map.addSource('admin-1', {
    type: 'vector',
    url: 'mapbox://mapbox.boundaries-adm1-v3'
  });

  // Add a layer with boundary polygons
  map.addLayer(
    {
      id: 'admin-1-fill',
      type: 'fill',
      source: 'admin-1',
      'source-layer': 'boundaries_admin_1',
      paint: {
        'fill-color': '#CCCCCC'
      }
    },
    // 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 will be rendered on top of
    // the
    'waterway-label'
  );
});

Add a worldview filter

The Mapbox Boundaries tilesets provide multiple worldview options in each tileset. That means that there are multiple versions of certain features, each intended for a different audience. Filters on each style layer determine which worldview you show.

You should add a worldview filter to every Boundaries layer you add to a map. Since you might add more Boundaries layers to a project later, it makes sense to define the filter as a variable. This example uses a variable called worldviewFilter:

map.on('load', function() {

  // Add source for admin-1 Boundaries
  map.addSource('admin-1', {
    type: 'vector',
    url: 'mapbox://mapbox.boundaries-adm1-v3'
  });

  var worldviewFilter = [
    "any",
    ["==", "all", ["get", "worldview"]],
    ["in", "US", ["get", "worldview"]]
  ];

  // Add a layer with boundary polygons
  map.addLayer(
    {
      id: 'admin-1-fill',
      type: 'fill',
      source: 'admin-1',
      'source-layer': 'boundaries_admin_1',
      filter: worldviewFilter,
      paint: {
        'fill-color': '#CCCCCC'
      }
    },
    // 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 will be rendered on top of
    // the
    'waterway-label'
  );
});

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