Add a vector tile layer

Learn how to add a vector tile layer to a map.

A vector tile layer is a hosted data layer in the ArcGIS Platform. The data is vector tile data. You can create a vector tile layer by publishing your data with data management tools. To display vector tiles in Mapbox GL JS, you create a source to retrieve the tiles, and a layer to display them.

In this tutorial, you display a parcels layer from a public vector tile service, using the default styling.

Prerequisites

You need a free ArcGIS developer account to access your dashboard and API keys. The API key must be scoped to access the services used in this tutorial.

Steps

Create a new pen

  1. To get started, either complete the Display a map tutorial or .

Set the API key

To access ArcGIS location services, you need an API key.

  1. Go to your dashboard to get an API key.

  2. In CodePen, update apiKey to use your key.

    Change line
              
    //
    
    const apiKey = "YOUR-API-KEY";
    const basemapEnum = "ArcGIS:Streets";
    const map = new mapboxgl.Map({
      container: "map", // the id of the div element
      style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&apiKey=${apiKey}`,
      zoom: 12, // starting zoom
      center: [-118.805, 34.027] // starting location [longitude, latitude]
    });
    

Add a load event handler

You need to wait for the map to be completely loaded before adding any layers

  1. Add an event handler to the map load event.

    For more information about the load event, see the Mapbox GL JS documentation.

    Add line.Add line.Add line.Add line.
                                                                 
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
        <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js"></script>
        <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" rel="stylesheet" />
        <style>
          html,
          body,
          #map {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
          }
        </style>
      </head>
    
      <body>
        <div id="map"></div>
      </body>
    
      <script>
        const apiKey = "YOUR-API-KEY";
        const basemapEnum = "ArcGIS:Streets";
        const map = new mapboxgl.Map({
          container: "map", // the id of the div element
          style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&apiKey=${apiKey}`,
          zoom: 12, // starting zoom
          center: [-118.805, 34.027] // starting location [longitude, latitude]
        });
    
        map.once("load", () => {
          // This code runs once the base style has finished loading.
    
          map.addSource("parcels", {
            type: "vector",
            tiles: ["https://vectortileservices3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_Mountains_Parcels_VTL/VectorTileServer/tile/{z}/{y}/{x}.pbf"]
          });
    
          map.addLayer({
            id: "parcels-fill",
            type: "fill",
            source: "parcels",
            "source-layer": "Santa_Monica_Mountains_Parcels",
            paint: {
              "fill-color": "hsl(200, 80%, 50%)",
              "fill-opacity": 0.5,
              "fill-outline-color": "white"
            }
          });
    
        });
    
      </script>
    
    </html>

Add a vector tile source

You use a source of type vector to add the vector tiles. The source tells Mapbox GL JS how to access the data for the layer, but does not visually add it to the map.

  1. Inside the load event handler, add a vector tile source with id parcels.

    While there are several types of source, the two most common are vector (for vector tiles) and geojson (for a set of features represented as GeoJSON).

    For more information, see the Mapbox GL JS Style Specification

    Add line.Add line.Add line.Add line.
                                                                 
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
        <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js"></script>
        <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" rel="stylesheet" />
        <style>
          html,
          body,
          #map {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
          }
        </style>
      </head>
    
      <body>
        <div id="map"></div>
      </body>
    
      <script>
        const apiKey = "YOUR-API-KEY";
        const basemapEnum = "ArcGIS:Streets";
        const map = new mapboxgl.Map({
          container: "map", // the id of the div element
          style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&apiKey=${apiKey}`,
          zoom: 12, // starting zoom
          center: [-118.805, 34.027] // starting location [longitude, latitude]
        });
    
        map.once("load", () => {
          // This code runs once the base style has finished loading.
    
          map.addSource("parcels", {
            type: "vector",
            tiles: ["https://vectortileservices3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_Mountains_Parcels_VTL/VectorTileServer/tile/{z}/{y}/{x}.pbf"]
          });
    
          map.addLayer({
            id: "parcels-fill",
            type: "fill",
            source: "parcels",
            "source-layer": "Santa_Monica_Mountains_Parcels",
            paint: {
              "fill-color": "hsl(200, 80%, 50%)",
              "fill-opacity": 0.5,
              "fill-outline-color": "white"
            }
          });
    
        });
    
      </script>
    
    </html>

Add a fill layer

A layer in Mapbox GL JS is a visual representation of the data within one source. Use a layer of type fill to display the parcels.

  1. Use addLayer to add a fill layer with id parcels-fill. Set source to parcels to reference the source you just created, and source-layer as Parcels to reference the specific layer within the vector tileset. Add paint properties to color the parcels light blue.

    The type property defines how it will be displayed. Commonly used layer types include circle, line, fill and symbol (used for text and icons).

    The id property is an identifier you choose. You will need it if you want to manipulate the layer, such as hiding it or changing its properties dynamically.

    The source property references the id property of the source you just created.

    The source-layer property tells Mapbox GL JS which layer within the vector tiles to display. If you enter the source-layer property incorrectly, nothing will display.

    The paint properties control the visual attributes of the layer and are specific to the type of layer.

    For more information, see the Mapbox GL JS Style Specification.

    Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
                                                                 
    <!DOCTYPE html>
    <html>
      <head>
        <meta charset="utf-8" />
        <meta name="viewport" content="initial-scale=1,maximum-scale=1,user-scalable=no" />
        <script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js"></script>
        <link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" rel="stylesheet" />
        <style>
          html,
          body,
          #map {
            padding: 0;
            margin: 0;
            height: 100%;
            width: 100%;
            font-family: Arial, Helvetica, sans-serif;
            font-size: 14px;
            color: #323232;
          }
        </style>
      </head>
    
      <body>
        <div id="map"></div>
      </body>
    
      <script>
        const apiKey = "YOUR-API-KEY";
        const basemapEnum = "ArcGIS:Streets";
        const map = new mapboxgl.Map({
          container: "map", // the id of the div element
          style: `https://basemaps-api.arcgis.com/arcgis/rest/services/styles/${basemapEnum}?type=style&apiKey=${apiKey}`,
          zoom: 12, // starting zoom
          center: [-118.805, 34.027] // starting location [longitude, latitude]
        });
    
        map.once("load", () => {
          // This code runs once the base style has finished loading.
    
          map.addSource("parcels", {
            type: "vector",
            tiles: ["https://vectortileservices3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Santa_Monica_Mountains_Parcels_VTL/VectorTileServer/tile/{z}/{y}/{x}.pbf"]
          });
    
          map.addLayer({
            id: "parcels-fill",
            type: "fill",
            source: "parcels",
            "source-layer": "Santa_Monica_Mountains_Parcels",
            paint: {
              "fill-color": "hsl(200, 80%, 50%)",
              "fill-opacity": 0.5,
              "fill-outline-color": "white"
            }
          });
    
        });
    
      </script>
    
    </html>

Run the app

In CodePen, run your code to display the map.

You should see the vector tile layer with parcels displayed on the basemap layer.

What's next?

Learn how to use additional ArcGIS location services in these tutorials: