Set basemap | ArcGIS Maps SDK for Kotlin

View on GitHub

Sample 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

Create a Map object with the arcGISImagery basemap style.
Display the map using the MapView composable from the ArcGIS Maps SDK for Kotlin Toolkit.
Load BasemapStylesService to retrieve the available basemap styles.
For each BasemapStyleInfo returned, create a BasemapGalleryItem and display them in the BasemapGallery Toolkit composable.
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.

Sample Code

MainActivity.kt

SetBasemapViewModel.kt

SetBasemapScreen.kt

/* 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

import android.os.Bundle
import androidx.activity.ComponentActivity
import androidx.activity.compose.setContent
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.Surface
import androidx.compose.runtime.Composable
import com.arcgismaps.ApiKey
import com.arcgismaps.ArcGISEnvironment
import com.esri.arcgismaps.sample.sampleslib.theme.SampleAppTheme
import com.esri.arcgismaps.sample.setbasemap.screens.SetBasemapScreen

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // authentication with an API key or named user is
        // required to access basemaps and other location services
        ArcGISEnvironment.apiKey = ApiKey.create(BuildConfig.ACCESS_TOKEN)

        setContent {
            SampleAppTheme {
                SetBasemapApp()
            }
        }
    }

    @Composable
    private fun SetBasemapApp() {
        Surface(color = MaterialTheme.colorScheme.background) {
            SetBasemapScreen(
                sampleName = getString(R.string.set_basemap_app_name)
            )
        }
    }
}

/* 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."
                )
            }
        }
    }
}

/* 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.screens

import androidx.compose.foundation.layout.Arrangement
import androidx.compose.foundation.layout.Box
import androidx.compose.foundation.layout.Column
import androidx.compose.foundation.layout.fillMaxSize
import androidx.compose.foundation.layout.fillMaxWidth
import androidx.compose.foundation.layout.heightIn
import androidx.compose.foundation.layout.padding
import androidx.compose.material3.BottomSheetDefaults
import androidx.compose.material3.BottomSheetScaffold
import androidx.compose.material3.ExperimentalMaterial3Api
import androidx.compose.material3.MaterialTheme
import androidx.compose.material3.SheetValue
import androidx.compose.material3.Text
import androidx.compose.material3.rememberBottomSheetScaffoldState
import androidx.compose.material3.rememberStandardBottomSheetState
import androidx.compose.runtime.Composable
import androidx.compose.runtime.rememberCoroutineScope
import androidx.compose.ui.Alignment
import androidx.compose.ui.Modifier
import androidx.compose.ui.platform.LocalWindowInfo
import androidx.compose.ui.unit.dp
import androidx.lifecycle.viewmodel.compose.viewModel
import com.arcgismaps.toolkit.basemapgallery.BasemapGallery
import com.arcgismaps.toolkit.basemapgallery.BasemapGalleryItem
import com.arcgismaps.toolkit.geoviewcompose.MapView
import com.esri.arcgismaps.sample.sampleslib.components.MessageDialog
import com.esri.arcgismaps.sample.sampleslib.components.SampleTopAppBar
import com.esri.arcgismaps.sample.setbasemap.components.SetBasemapViewModel
import kotlinx.coroutines.launch

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun SetBasemapScreen(sampleName: String) {
    val mapViewModel: SetBasemapViewModel = viewModel()
    val maxSheetHeight = LocalWindowInfo.current.containerDpSize.height / 2

    // Create a sheet state that starts expanded and allows dragging to collapse/expand
    val scaffoldState = rememberBottomSheetScaffoldState(
        bottomSheetState = rememberStandardBottomSheetState(initialValue = SheetValue.Expanded)
    )

    val scope = rememberCoroutineScope()

    BottomSheetScaffold(
        topBar = { SampleTopAppBar(title = sampleName) },
        scaffoldState = scaffoldState,
        sheetDragHandle = { BottomSheetDefaults.DragHandle() },
        sheetContent = {
            Column(
                modifier = Modifier
                    .fillMaxWidth()
                    .heightIn(max = maxSheetHeight)
                    .padding(12.dp),
                horizontalAlignment = Alignment.CenterHorizontally,
                verticalArrangement = Arrangement.spacedBy(4.dp)
            ) {
                Text(
                    text = "Basemap Gallery",
                    style = MaterialTheme.typography.titleLarge,
                    modifier = Modifier.padding(bottom = 8.dp)
                )
                Text(
                    text = "Choose a basemap style to change the map's basemap.",
                    style = MaterialTheme.typography.labelSmall,
                    modifier = Modifier.padding(bottom = 8.dp)
                )

                BasemapGallery(
                    basemapGalleryItems = mapViewModel.basemapGalleryItems,
                    onItemClick = { item: BasemapGalleryItem ->
                        mapViewModel.onBasemapGalleryItemClick(item)
                    }
                )
            }
        }
    ) { padding ->
        Box(modifier = Modifier.padding(padding)) {
            MapView(
                modifier = Modifier.fillMaxSize(),
                arcGISMap = mapViewModel.arcGISMap,
                onDown = { scope.launch { scaffoldState.bottomSheetState.partialExpand() } }
            )
        }

        // Display a dialog if the sample encounters an error
        mapViewModel.messageDialogVM.apply {
            if (dialogStatus) {
                MessageDialog(
                    title = messageTitle,
                    description = messageDescription,
                    onDismissRequest = ::dismissDialog
                )
            }
        }
    }
}