All docschevron-rightMapbox Boundarieschevron-rightarrow-leftGuideschevron-rightUse Boundaries v4 on a map

Use Boundaries v4 on 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.

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.

book
Migrating from v3

The use of promoteId while adding any Boundaries vector tiles sources is a requirement due to breaking changes to IDs introduced in v4. Failure to use 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.

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: "fill",
      source: "admin-1",
      "source-layer": "boundaries_admin_1",
      filter: worldviewFilter,
      paint: {
        "fill-color": "#CCCCCC",
        "fill-opacity": 0.5
      }
    },
    // 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"
  );
});

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