Skip to content
View on GitHubSample viewer app

Change a map's basemap.

Image of Set basemap sample

Use case

A basemap draws beneath all layers on a Map or Scene and is used to provide visual reference for the operational layers. Basemaps should be selected contextually. For example, in maritime applications, it would be more appropriate to use a basemap of the world's oceans as opposed to a basemap of the world's streets.

How to use the sample

Open the sample and browse the basemap list shown in the bottom sheet. Tap a basemap to set it as the map's basemap. The map updates immediately to reflect the new style.

How it works

  1. Create a Map object with the arcGISImagery basemap style.
  2. Display the map using the MapView composable from the ArcGIS Maps SDK for Kotlin Toolkit.
  3. Load BasemapStylesService to retrieve the available basemap styles.
  4. For each BasemapStyleInfo returned, create a BasemapGalleryItem and display them in the BasemapGallery Toolkit composable.
  5. When BasemapGalleryItem is tapped, update the current map's basemap using:
    • arcGISMap.setBasemap(Basemap(basemapStyleInfo.style))

Relevant API

  • ArcGISMap
  • Basemap
  • BasemapGallery
  • BasemapGalleryItem
  • BasemapStyle
  • BasemapStyleInfo
  • BasemapStylesService
  • MapView

Additional information

Organizational basemaps are a Portal feature allowing organizations to specify basemaps for use throughout the organization. Customers expect that they will have access to their organization's standard basemap set when they connect to a Portal. Organizational basemaps are useful when certain basemaps are particularly relevant to the organization, or if the organization wants to make premium basemap content available to their workers.

This sample uses the BasemapGallery toolkit component, which requires the ArcGIS Maps SDK for Kotlin Toolkit. The BasemapGallery toolkit component supports selecting 2D and 3D basemaps from any kind of source, such as ArcGIS Online, a user-defined portal, or a collection of Basemaps.

Tags

basemap, map

Sample Code

SetBasemapViewModel.ktSetBasemapViewModel.ktMainActivity.ktSetBasemapScreen.kt
Use dark colors for code blocksCopy
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
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
/* Copyright 2026 Esri
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 */

package com.esri.arcgismaps.sample.setbasemap.components

import android.app.Application
import androidx.compose.runtime.getValue
import androidx.compose.runtime.mutableStateListOf
import androidx.compose.runtime.mutableStateOf
import androidx.lifecycle.AndroidViewModel
import androidx.lifecycle.viewModelScope
import com.arcgismaps.geometry.Point
import com.arcgismaps.geometry.SpatialReference
import com.arcgismaps.mapping.ArcGISMap
import com.arcgismaps.mapping.Basemap
import com.arcgismaps.mapping.BasemapStyle
import com.arcgismaps.mapping.BasemapStyleInfo
import com.arcgismaps.mapping.BasemapStylesService
import com.arcgismaps.mapping.Viewpoint
import com.arcgismaps.toolkit.basemapgallery.BasemapGalleryItem
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialogViewModel
import kotlinx.coroutines.launch

class SetBasemapViewModel(application: Application) : AndroidViewModel(application) {
    // Map initialized with an imagery basemap to match the Swift sample
    val arcGISMap by mutableStateOf(
        ArcGISMap(BasemapStyle.ArcGISImagery).apply {
            // Initial viewpoint centered near Los Angeles, CA at a scale of 1:1,000,000
            initialViewpoint = Viewpoint(
                center = Point(
                    x = -118.4,
                    y = 33.7,
                    spatialReference = SpatialReference.wgs84()
                ),
                scale = 1e6
            )
        }
    )

    // Items displayed by the Basemap Gallery
    val basemapGalleryItems = mutableStateListOf<BasemapGalleryItem>()

    // Message dialog view model for handling error messages
    val messageDialogVM = MessageDialogViewModel()

    init {
        viewModelScope.launch {
            // Load the map and report any errors
            arcGISMap.load().onFailure { error ->
                messageDialogVM.showMessageDialog(
                    title = "Failed to load map",
                    description = error.message.toString()
                )
            }

            // Load available basemap styles from the BasemapStyles service and create gallery items
            val service = BasemapStylesService()
            service.load().onSuccess {
                val stylesInfo = service.info?.stylesInfo
                if (!stylesInfo.isNullOrEmpty()) {
                    stylesInfo.forEach { basemapStyleInfo ->
                        basemapGalleryItems.add(BasemapGalleryItem(basemapStyleInfo))
                    }
                } else {
                    messageDialogVM.showMessageDialog(
                        title = "No basemap styles available",
                        description = "BasemapStylesService returned no styles."
                    )
                }
            }.onFailure { error ->
                messageDialogVM.showMessageDialog(
                    title = "Failed to load basemap styles",
                    description = error.message.toString()
                )
            }
        }
    }

    /**
     * Updates the map's basemap using the selected [BasemapStyleInfo].
     */
    fun updateBasemapFromStyleInfo(basemapStyleInfo: BasemapStyleInfo) {
        arcGISMap.setBasemap(Basemap(basemapStyleInfo.style))
    }

    /**
     * Convenience function to handle a BasemapGalleryItem click.
     */
    fun onBasemapGalleryItemClick(item: BasemapGalleryItem) {
        when (val tag = item.tag) {
            is BasemapStyleInfo -> updateBasemapFromStyleInfo(tag)
            else -> {
                messageDialogVM.showMessageDialog(
                    title = "Unsupported item type",
                    description = "The selected gallery item is not a BasemapStyleInfo."
                )
            }
        }
    }
}

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