View on GitHub

Specify a map’s spatial reference.

Image of set spatial reference

Use case

Choosing the correct spatial reference is important for ensuring accurate projection of data points to a map.

How to use the sample

Pan and zoom around the map. Observe how the map is displayed in the World Bonne spatial reference. Pick a different spatial reference and see the map reprojected.

How it works

  1. Instantiate an ArcGISMap object using a spatial reference.
  2. Instantiate a Basemap object using an ArcGISMapImageLayer object.
  3. Set the basemap to the map.
  4. Set the map to an ArcGISMapViewController object.
  5. Change the map’s spatial reference using the setSpatialReference method.

The ArcGIS map image layer will reproject into the spatial reference set to the map (such as World Bonne (WKID: 54024)), and not the map service’s default spatial reference.

Relevant API

  • ArcGISMap
  • ArcGISMapImageLayer
  • ArcGISMapView
  • ArcGISMapViewController
  • Basemap
  • SpatialReference

About the data

This sample uses a World Cities Population map service that displays world cities symbolized based on population.

Additional information

Operational layers will automatically project to this spatial reference when possible. There are 3 kinds of layer reprojection behaviors:

  • Reprojected on device (on-the-fly reprojection), such as a FeatureLayer created from a mobile geodatabase
  • Reprojected from the service, such as an ArcGISMapImageLayer
  • Not able to reproject, such as an ArcGISTiledLayer with defined spatial reference in its tile cache. These layers might be able to reproject in a future update.

For more information, check out the API reference doc for setSpatialReference method.

Tags

coordinate system, project, projection, spatial reference, Web Mercator, WGS84, WKID

Sample code

set_spatial_reference.dart
// 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
//
// https://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.
//
import 'package:arcgis_maps/arcgis_maps.dart';
import 'package:arcgis_maps_sdk_flutter_samples/common/common.dart';
import 'package:flutter/material.dart';
class SetSpatialReference extends StatefulWidget {
const SetSpatialReference({super.key});
@override
State<SetSpatialReference> createState() => _SetSpatialReferenceState();
}
class _SetSpatialReferenceState extends State<SetSpatialReference>
with SampleStateSupport {
// Create a controller for the map view.
final _mapViewController = ArcGISMapView.createController();
// A flag for when the map view is ready and controls can be used.
var _ready = false;
// The spatial reference currently selected in the dropdown.
SpatialReference? _selectedSpatialReference;
// Stores the spatial references available in the dropdown.
final _spatialReferences = <DropdownMenuEntry<SpatialReference>>[];
@override
void initState() {
super.initState();
// Add spatial references to the dropdown menu.
_spatialReferences.addAll([
DropdownMenuEntry(
value: SpatialReference(wkid: 102299),
label: 'Berghaus Star AAG',
),
DropdownMenuEntry(value: SpatialReference(wkid: 54050), label: 'Fuller'),
DropdownMenuEntry(
value: SpatialReference(wkid: 27200),
label: 'New Zealand Map Grid',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 102018),
label: 'North Pole Stereographic',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 54090),
label: 'Peirce Quincuncial',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 32610),
label: 'UTM Zone 10 N',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 54024),
label: 'World Bonne',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 54052),
label: 'World Goode Homolosine',
),
DropdownMenuEntry(
value: SpatialReference(wkid: 102038),
label: 'World Orthographic',
),
DropdownMenuEntry(
value: SpatialReference.webMercator,
label: 'Web Mercator',
),
DropdownMenuEntry(value: SpatialReference.wgs84, label: 'WGS 84'),
]);
}
@override
Widget build(BuildContext context) {
return Scaffold(
body: SafeArea(
top: false,
left: false,
right: false,
child: Stack(
children: [
Column(
children: [
Expanded(
// Add a map view to the widget tree and set a controller.
child: ArcGISMapView(
controllerProvider: () => _mapViewController,
onMapViewReady: onMapViewReady,
),
),
Center(
// A dropdown button to select the spatial reference.
child: DropdownMenu(
dropdownMenuEntries: _spatialReferences,
textAlign: TextAlign.center,
onSelected: (spatialReference) {
// Return if no spatial reference was selected.
if (spatialReference == null) return;
// Update the selected spatial reference.
setState(() {
_selectedSpatialReference = spatialReference;
});
// Set the map's spatial reference to the selected value.
_mapViewController.arcGISMap?.setSpatialReference(
spatialReference,
);
},
initialSelection: _selectedSpatialReference,
),
),
],
),
// Display a progress indicator and prevent interaction until state is ready.
LoadingIndicator(visible: !_ready),
],
),
),
);
}
void onMapViewReady() {
// Create a map using the World Bonne spatial reference.
final map = ArcGISMap(spatialReference: SpatialReference(wkid: 54024));
// Create a map image layer.
final mapImageLayer = ArcGISMapImageLayer.withUri(
Uri.parse(
'https://sampleserver6.arcgisonline.com/arcgis/rest/services/SampleWorldCities/MapServer',
),
);
// Create a basemap from the map image layer.
map.basemap = Basemap.withBaseLayer(mapImageLayer);
// Set the map to the map view controller.
_mapViewController.arcGISMap = map;
// Set the initial selected spatial reference and enable the sample UI.
setState(() {
_selectedSpatialReference = map.spatialReference;
_ready = true;
});
}
}