Basemap layers
What is a basemap layer?
A basemap layer is a layer that provides the overall visual context for a map or scene. It typically contains geographic features such as continents, lakes, administrative boundaries, streets, cities, and place names. These features are represented with different styles provided by the basemap layer service such as streets, topographic, and imagery. The style you choose depends on the type of application and the visualization you would like to create.
You can use a basemap layer to:
- Display different types of geographic data of the world for both maps and scenes.
- Display default vector tile basemap styles such as streets navigation, light gray canvas, and osm.
- Display custom basemap styles with your own colors, glyphs, and fonts.
- Display default image tile basemap layers for satellite imagery and hillshade.
How a basemap layer works
A basemap layer provides the visual foundation for a mapping application. It typically contains data with global coverage and is the first layer added to a map or scene. The main data source for a basemap layer is the basemap layer service. When a view displays a map, a basemap layer is the first layer to draw, followed by data layers, and then graphics.
Figure 1: A basemap layer provides visual context for a map or scene.
Types of basemap layers
The Basemap layer service provides a number of vector tile and image tile basemap layers that you can use to build different types of mapping applications. Each of the basemap layer styles is defined in an enumeration. For example, you can use the Navigation style to create an application that supports driving directions, or you can use Imagery to create an application that displays a real-world view of the earth.
Vector tile basemaps
Vector tile basemaps are pre-styled vector tile layers provided by the basemap layer service. Vector tile layers are high-performance and well suited for displaying high density geographic data as vector tile data. Vector tile layers are based on the Mapbox specification.
To access the default vector tile basemaps styles, most APIs provide enumerations. If they are not available, you can access them directly with the service URL.
Service URL
Learn more about standard and enhanced endpoints in Service endpoints.
Example vector tile basemap styles
- ArcGIS:LightGray
- ArcGIS:DarkGray
- ArcGIS:Navigation
- ArcGIS:NavigationNight
- ArcGIS:Streets
- ArcGIS:StreetsNight
- ArcGIS:Topographic
- OSM:Standard
Custom vector tile basemap styles
A custom basemap layer style, also known as a basemap style, is a style that you define to create a custom visualization for a vector tile basemap layer. To do so, you use the ArcGIS Vector Tile Style Editor. You can edit any of the layer's properties such as the fill color, glyphs, and fonts for labels. After styling a basemap, you can save it in ArcGIS Online, and then use it in your applications.
Image tile basemaps
Image tile layers are pre-rendered images hosted in ArcGIS. The images are pre-rendered and stored on the server at different scales and resolutions. Client applications request images for the appropriate scale and zoom level for the map.
The URL and the most common image tile basemap styles are listed below.
Service URL
Learn more about standard and enhanced endpoints in Service endpoints.
Example image tile basemap styles
- ArcGIS:Imagery
- ArcGIS:Imagery:Standard
- ArcGIS:Imagery:Labels
- ArcGIS:Oceans
- ArcGIS:Hillshade:Light
- ArcGIS:Hillshade:Dark
Multi-layer basemap layers
A basemap layer can be composed of one or more layers. Many default styles combine multiple layers. For example:
ArcGIS:
combines a layer of streets with a backing hillshade layer to provide topographic context.Streets Relief ArcGIS:
usesStreets Relief ArcGIS:
overlaid on top ofStreets Relief: Base ArcGIS:
.Hillshade: Light ArcGIS:
combines a layer of satellite imagery with a reference layer of labels and boundaries.Imagery ArcGIS:
usesImagery ArcGIS:
as the base layer andImagery: Standard ArcGIS:
as the reference layer.Imagery: Labels
See Basemap layer service to learn more.
You can create your own multi-layer basemap by combining layers and specifying which should be treated as reference layers. See the Display a multi-layer basemap layer example.
Examples
Display a basemap layer
This example shows how to use different enumerations to display basemap layers from the basemap layer services. Where enumerations are not available, you can access the service style or layer with its URL.
Steps
- Create a map or scene.
- Reference a basemap layer from the basemap layer service.
- Add the basemap to the map or scene.
- Use an interface to allow users to change the basemap layer.
Topographic
Imagery
Navigation
Light gray canvas
Display a multi-layer basemap layer
This example shows how to use multiple layers together as a single basemap layer. You can use item IDs for each layer in a multi-layer basemap layer.
Steps
- Reference two or more layers using their item IDs.
- Create a basemap that uses these layers as base layers or reference layers.
- Create a map or scene using the basemap.
Tutorials

Display a map
Create and display a map with the basemap layer service.

Display a scene
Display a scene with the basemap layer service.

Add a point, line, and polygon
Display point, line, and polygon graphics in a map.

Add a feature layer
Access and display point, line, and polygon features from a feature service

Display a web map
Create and display a map from a web map.

Display a web scene
Create and display a scene from a web scene.

Change the basemap layer
Switch a basemap layer from streets to satellite imagery.
Services
Basemap layer service
Access streets, satellite, and other basemap styles for maps and scenes.
API support
2D Display | 3D Display | Basemap layers | Data layers | Graphics | Web maps | Web scenes | |
---|---|---|---|---|---|---|---|
ArcGIS API for JavaScript | |||||||
ArcGIS Runtime API for Android | |||||||
ArcGIS Runtime API for iOS | |||||||
ArcGIS Runtime API for Java | |||||||
ArcGIS Runtime API for .NET | |||||||
ArcGIS Runtime API for Qt | |||||||
ArcGIS API for Python | |||||||
Esri Leaflet | 1 | 2 | |||||
MapLibre GL JS | 1 | 2 | |||||
OpenLayers | 1 | 2 | |||||
ArcGIS REST JS | 3 | 3 | 3 | 3 |
- 1. Access via Feature layer or Image tile layer.
- 2. Access via layers.
- 3. Access via HTTP request and authentication.