Skip To Content ArcGIS for Developers Sign In Dashboard

Build a new map

A map gives you a structure for organizing your geographical data so your users can view, explore, and interact with it. This page describes how to design and build a map with code and then save it for later use by another app or by a different user.


You can also create a map for use in your ArcGIS Runtime app using ArcGIS Online's map viewer (how-to steps are in ArcGIS Online Help's Get started with maps page).

To build a map with code for your ArcGIS Runtime app, you use this API to create a map. In this API, the map is represented by the Map class that gives you all the methods and properties you need to set the background layer, add the operational layers, set the spatial reference, add bookmarks, and save the map. If you wish to display the map and allow users to interact with it then you pass the map to the MapView class.

Map design considerations

When designing a map you must:

  • Choose a background for your map so that your users can orient themselves. Esri provides a number of standard basemaps that you can use as a background or you can use other providers, such as your organization's basemaps. Alternatively, you can construct a basemap in code.
  • Ensure that you specify a spatial reference for your map that allows the layers to be aligned and displayed together. It will be more efficient if all of your operational layers have the same spatial reference as the map and basemap because the operational layers will not need to be reprojected.
  • Start the map display in a specific and recognizable geographical area.
  • Only show the data that your users need.
    • Set the minimum and maximum scale thresholds for layers so only useful information is displayed at each scale.
    • You may wish to set a map reference scale. The reference scale of the map is the scale at which a user should view the map for the feature symbols and text to appear at their authored size. By setting a reference scale, layers and labels will not resize based on changes of scale in the map view.

Construct the map

This API lets you declare maps and their content in nested declarations. You can declare basemap and operational layers and graphic overlays. This is the simplest and most common way to add layers into a map. Here is an example of declaring a map with an Esri Imagery basemap that is centered on an X and Y location.

Map {
    id: imageryZoomedMap
    BasemapImagery { }
    initialViewpoint: ViewpointCenter {
        center: Point { x: -13200000; y: 4020000; spatialReference: SpatialReference { wkid: 102100 } }

Also, you can add layers to the map using JavaScript code. See Add operational layers later in this topic for details.

Create a basemap

A basemap is composed of a collection of base layers and reference layers. The base layer can give your map a recognizable background so that your operational layers are displayed in context. The reference layer can display useful text labels such as the city, street, river or mountain names.

Base layers are displayed at the bottom of a map, and reference layers are displayed at the top, with the map’s operational layers sandwiched between them. The content of a basemap is typically static and does not change frequently so tiled layers make good basemap layers as they provide faster access to relatively static maps. (For more information see Layer types.) As discussed previously, ArcGIS Online provides a number of ready-to-use standard basemaps such as the World imagery, topographic, oceans, streets, and so on. Or, you can add basemaps from your organization or another public service. Also, you can create your own basemap by combining (mashing up) layers.

Standard ArcGIS Online basemaps

To use, instantiate a basemap, such as the ArcGIS Online World Streets basemap.

Map {
    id: mapFromBaseMapDefaultProperty2
    BasemapStreets { }

A single layer

You can also create your own basemap from a single layer, as shown in this example.

Map {
    id: basemapMap

    Basemap {
        id: basemap2
        ArcGISTiledLayer {
            id: arcGISTiledLyr2
            url: Globals.url_WorldImageryMapServer

Combining layers into one basemap

You can combine a number of layers to create a single basemap as long as the layers are capable of being displayed in the same spatial reference (that is, either a layer is already in the same spatial reference as the other layers or it can be re-projected to the spatial reference of the other layers). In the following code example, the first layer added to the set of basemap layers establishes the spatial reference of the basemap, making it 3857 (you can see this number if you enter the URI in the code sample into your browser's address box and look for "spatial reference" in the resulting page). The second basemap layer, being a map image layer, is requested from the map server in spatial reference set by the first layer, 3857.

Map {
    id: twoLayerBasemapMap

    Basemap {
        id: basemapTwoLayer
        ArcGISTiledLayer {
            id: arcGISTiledLyr3
            url: Globals.url_WorldImageryMapServer
        ArcGISMapImageLayer {
            id: arcGISMapImageLyr3
            url: Globals.url_UsaMedianHomeValueMapServer


In terms of the map's spatial reference, it's important to understand the following:

  • If a map does not have a spatial reference, it will automatically be set by the map's first basemap.
  • If you add a basemap to a map that already has a spatial reference, it must have the same spatial reference as the map; otherwise it will fail to draw. The same is true if you exchange one basemap for another.
  • If the map does not have a basemap, then the map will adopt the spatial reference of the first operational layer that is added to the map.

Just like the map, the basemap loads asynchronously. This is described in more detail in the loadable pattern topic.

A group layer cannot be included in a basemap.

Add operational layers

Operational layers are a category of layers that provide geographic content that is of specific interest to the app. Your choice of layer type will determine whether you can edit, query, identify or overwrite the layer rendering. For more information about the types of operational layers please refer to the topic Layer types. Typically, operational layers contain data that changes more frequently than that of a basemap.

To add an operational layer to the map, add the layer to the map's operational layers list.

First, declare the map.

Map {
    id: initMap2

Also, declare a layer to add to the map. Declare the layer outside the body of the map.

ArcGISTiledLayer {
    id: operationalLayer1
    url: Globals.url_WorldImageryMapServer

Later in a function, append the layer to the map's operational layer list.

A layer that is added first is placed directly above the basemap and is in the 0th position in the map's operational layers list. If you add additional layers they are placed above the last layer and their position will be incremented by one. So the next layer will be in the first, then the next in the second position, and so on.


If your code adds operational layers to an existing map by nesting them in the map’s declaration, the map’s original list of operational layers is overridden to contain only the added layers. To keep the map’s original operational layers and add new ones, wait until the map is loaded before adding operational layers. You can declare new operational layers outside the map’s declaration, and use a signal handler to wait for the map to finish loading before adding the new layers. See the next section of this topic for details about loading a map and its layers.

If you wish to, you can insert a layer into the list of operational layers at a specific position.


All operational layers are added to the map in the same way and also conform to the asynchronous loading pattern as detailed in the Loadable pattern topic.

Operational layer properties

Each operational layer has a set of default properties. You can modify these properties so that they are more appropriate for your map. For example, you can:

  • Set the maximum and minimum scale at which the layer is visible.
  • Change the opacity of the layer.
  • Change the visibility of the layer.
  • Override the rendering.
  • Specify a definition expression.
  • Change the order in which the layers are displayed in the map.

By adding operational layers to a group layer, you can control some of these properties on a group of layers simultaneously.

For more information please explore the specific layer and sublayer classes.

Load the map and its layers

The map has been designed to load as quickly as possible. You will be able to access the map and set its properties and iterate through its layers even if a layer has failed or a layer's service response is slow. One broken layer should not prevent the entire map from being used. A map should not load layers that are not needed. The advantage of this design is that the map can be used without having to wait for all of the layer's to be available.

When you construct the map, its load status will be LoadStatusNotLoaded. You can load the map (initiate the map's load cycle) either by:

  • Calling load on the map
  • Or, by setting the map on the mapview.

    First, declare the MapView and set some properties on it.

    MapView {
        id: view
        anchors.fill: parent
        visible: parent.visible
        focus: visible
        clip: true
        viewInsets {
            right: popupWindow.visible && popupView.x > 0 && popupWindow.currentDisplayMode === "animate" ?
                       (parent.width - popupView.x) / scaleFactor : 0
        Keys.onEscapePressed: {
        zoomByPinchingEnabled: true
        rotationByPinchingEnabled: true
        wrapAroundMode: Enums.WrapAroundModeEnabledWhenSupported
        magnifierEnabled: true
        allowMagnifierToPanMap: true
        BackgroundGrid {
            gridLineColor: "lightGreen"
            color: "lightBlue"
            gridLineWidth: 1.5
            gridSize: 15.0
        ViewLabelProperties {
            animationEnabled: true
            labelingEnabled: true

    Then, declare the Map within the MapView's declaration. The user-defined function checkLoadStatus does something appropriate when an object's loadStatus changes.

    // Declare the map in the mapview
    Map {
        id: map
        initialViewpoint: vc
        Basemap {
            ArcGISTiledLayer {
                url: url_WorldStreetMap
                onLoadStatusChanged: {
                    checkLoadStatus("ArcGISTiledLayer", loadStatus);
            onLoadStatusChanged: {
                checkLoadStatus("basemap", loadStatus);
        ArcGISMapImageLayer {
            id: mapImageLayer
            url: url_UsaMedianHomeValueMapServer
        ArcGISMapImageLayer {
            id: mapImageLayerUSA
            url: url_UsaMapServer
            visible: false
        FeatureLayer {
            id: featureLayer
            ServiceFeatureTable {
                url: url_FcTest25FeatureServer
        FeatureLayer {
            id: featureLayer2
            ServiceFeatureTable {
                url: url_FcTest13FeatureServer
                useAdvancedSymbology: true
        onLoadStatusChanged: {
            checkLoadStatus("map", loadStatus);

Upon completion of the map's load cycle, the map's load status will be LoadStatusLoaded, indicating that:

  • The map's spatial reference has been defined by the basemap's spatial reference. The Esri basemaps defined in the API all use Web Mercator.
  • The map's initial viewpoint has been specified, for example, by setting the map's latitude, longitude and level of detail. (The levelOfDetail value sets the scale or resolution at which the map is displayed.)
  • The map's list of layers has been created.

The map can be in a loaded state and ready for user interaction even if the individual layers have not finished loading. The map's layers could be in a LoadStatusLoaded, LoadStatusNotLoaded, or LoadStatusFailedToLoad state. Please explore the Loadable pattern for more information on loading maps and layers.

Save the map to a portal

You have designed and built a map. Now you can save the map so you, or other users, can view at a later time. To save the map to the ArcGIS Enterprise portal or your organization's portal the following conditions must be met:

  • The map must be in a loaded state.
  • Any layers that you wish to save must be in a loaded state.
  • You must be authenticated to a portal.

Have the map and layers been loaded?

Before attempting to save the map it is prudent to confirm that the map is loaded and that the layers are loaded. If a layer has failed to load you may decide to save the map without the layer or investigate why you cannot access the layer. This will depend on your workflow.


If a layer has an invalid URL then the layer will have a layer type of Unknown Layer. This layer will not be saved to the map.

var allLoaded = "yes";
if (initMap2.loadStatus !== Enums.LoadStatusLoaded ) {
    allLoaded = "no";
initMap2.operationalLayers.forEach(function(opLyr) {
    if (opLyr.loadStatus !== Enums.LoadStatusLoaded ) {
        allLoaded = "no";

Has the user authenticated with the portal?

When your user authenticates to a portal (including ArcGIS Online) they have access to the maps that they own. When they log into ArcGIS Online or ArcGIS Enterprise portal, these maps are visible in a set of folders under the My Content tab. In ArcGIS Enterprise portal, the My Content filter is selected by default. When a user saves a map with this API, the map is saved into a folder under My Content and is accessible from there.

To authenticate a user to a portal you must create a portal object, provide the essential credentials and then asynchronously load the portal. Just like map and layer classes, the Portal class conforms to the Loadable pattern.

portal.url = portalUrl; // ex:
var credential = ArcGISRuntimeEnvironment.createObject("Credential", {username:data.username, password:data.password});
portal.credential = credential;

For more information on authenticating with a portal, see Access the ArcGIS Platform.

Save the map

Saving a map to the portal creates a new web map portal item. The map is placed in a folder of your choice in the My Content area of the authenticated user. For full details on how to save the map to a portal, see Save a map.

Share the map

By default, the map that the user adds to the portal is only accessible to that user. The map is not available to others. For example, the map does not appear in search results and is not part of any group. There are several options for sharing a map. The options are described in the Share a portal item topic.