Use Boundaries v4 on a map | Mapbox Boundaries | Mapbox Docs

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.

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.

Was this page helpful?

Basic example​

Basic example