Display a custom basemap style

Learn how to add a custom vector basemap layer to a map.

A basemap layer provides the visual context for a map. You can use the default basemap layer styles provided by the basemap styles service or you can create your own custom styles with the ArcGIS Vector Tile Style Editor for specific mapping applications.

In this tutorial you use OpenLayers to display a styled vector basemap layer in a map.

Prerequisites

You need an ArcGIS Location Platform or ArcGIS Online account.

Steps

Create a new pen

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

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

  1. Go to the Create an API key tutorial and create an API key with the following privilege(s):

    • Privileges
      • Location services > Basemaps
    • Item access
      • Note: If you are using your own custom data layer for this tutorial, you need to grant the API key credentials access to the layer item. Learn more in Item access privileges.
  2. Copy the API key access token to your clipboard when prompted.

  3. In CodePen, update the accessToken variable to use your access token.

    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    const accessToken = "YOUR_ACCESS_TOKEN";
    const basemapId = "arcgis/streets";
    const basemapURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapId}?token=${accessToken}`;
    olms.apply(map, basemapURL);
    

To learn about the other types of authentication available, go to Types of authentication.

Add the vector tile layer

You can access a basemap layer by referencing its item ID. You can find a layer's item ID by accessing it in your portal or the ArcGIS Vector Tile Style Editor.

  1. Go to the Forest and Parks Canvas vector tile layer in the portal and find its item ID. The ID is at the end of the URL.

  2. Change the basemapId from arcgis/streets to your own item ID and the basemapURL to enable your custom item.

    Expand
    Use dark colors for code blocks
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    30
    31
    32
    33
    34
    35
    36
    37
    38
    39
    40
    41
    42
    43
    44
    45
    46
    47
    48
    49
    50
    51
    52
          const accessToken = "YOUR_ACCESS_TOKEN";
    
          const basemapId = "6976148c11bd497d8624206f9ee03e30"; // Custom vector tile style
    
          const basemapURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/items/${basemapId}?token=${accessToken}`;
    
          olms.apply(map, basemapURL);
    
    Expand

Run the app

In CodePen, run your code to display the map.

It should display the Forest and Parks Canvas vector basemap layer.

What's next?

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

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.