Display a map

Learn how to create and display a map with a basemap layer.

A map contains layers of geographic data. A map contains a basemap layer and, optionally, one or more data layers. You can display a specific area of a map by using a map view and setting the location and zoom level.

In this tutorial, you create and display a map of the Santa Monica Mountains in California using the topographic basemap layer.

The map and code will be used as the starting point for other 2D tutorials.

Prerequisites

Before starting this tutorial:

You need an ArcGIS Location Platform or ArcGIS Online account.
Your system meets the system requirements and you have set up your environment for Flutter development.
You need an IDE for Flutter - we recommend VS Code.

Steps

Create a new Flutter app

Open VS Code, then select Open Folder... in the welcome tab. Choose your preferred project location.
Go to View > Terminal.
In the terminal window, use the following command to create a new Flutter app called display_a_map. Set your required target platform(s) and an org name, com.example.app.
Use dark colors for code blocksCopy
```
1
flutter create -e display_a_map --platforms ios,android --org com.example.app
```

Add ArcGIS Maps SDK for Flutter

Add a dependency to the arcgis_maps package.

In VS Code's terminal, change the directory to your new project:
Use dark colors for code blocksCopy
```
1
  cd display_a_map
```
Run:
Use dark colors for code blocksCopy
```
1
dart pub add arcgis_maps
```
Run:
Use dark colors for code blocksCopy
```
1
flutter pub upgrade
```
Lastly, run:
Use dark colors for code blocksCopy
```
1
dart run arcgis_maps install
```

Platform specific configuration

Update the minimum requirements by editing android/app/build.gradle file in your project:

build.gradle
Use dark colors for code blocks
7
7
7
7
7
7
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
31
31
31
31
31
31
31
31
31
31
31
31
31
Change lineChange lineandroid {
    namespace = "com.example.app.display_a_map"
    compileSdk = flutter.compileSdkVersion
    ndkVersion = "25.2.9519653"

    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_1_8
        targetCompatibility = JavaVersion.VERSION_1_8
    }

    kotlinOptions {
        jvmTarget = JavaVersion.VERSION_1_8
    }

    defaultConfig {
        // TODO: Specify your own unique Application ID (https://developer.android.com/studio/build/application-id.html).
        applicationId = "com.example.app.display_a_map"
        // You can update the following values to match your application needs.
        // For more information, see: https://flutter.dev/to/review-gradle-config.
        minSdk = 26
        targetSdk = flutter.targetSdkVersion
        versionCode = flutter.versionCode
        versionName = flutter.versionName
    }

Update the Kotlin version by editing android/settings.gradle file in your project:

settings.gradle
Use dark colors for code blocks
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
18
19
20
21
22
23
23
23
Change lineplugins {
    id "dev.flutter.flutter-plugin-loader" version "1.0.0"
    id "com.android.application" version "8.1.0" apply false
    id "org.jetbrains.kotlin.android" version "1.9.0" apply false
}

Add a permission to android/app/src/main/AndroidManifest.xml to access online resources:

AndroidManifest.xml
Use dark colors for code blocks
2
3
4
5
6
7
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
8
Add line.
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
    <uses-permission android:name="android.permission.INTERNET" />
    <application
        android:label="display_a_map"
        android:name="${applicationName}"
        android:icon="@mipmap/ic_launcher">

Set iOS 16.0 minimum by editing the ios/Podfile file. Uncomment the line and update the version number.

Podfile
Use dark colors for code blocks
2
3
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
Change line
# Uncomment this line to define a global platform for your project
platform :ios, '16.0'

Add the Runtimecore and arcgis_maps_ffi pods to the Runner target section.

Podfile
Use dark colors for code blocks
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
31
32
33
34
35
36
37
38
39
40
41
42
42
42
42
42
42
42
Change lineChange linetarget 'Runner' do
  use_frameworks!
  use_modular_headers!

  pod 'Runtimecore', :podspec => '../arcgis_maps_core/ios/Runtimecore.podspec'
  pod 'arcgis_maps_ffi', :podspec => '../arcgis_maps_core/ios/arcgis_maps_ffi.podspec'

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
  target 'RunnerTests' do
    inherit! :search_paths
  end
end

Use pod update to configure Pods.
Use dark colors for code blocksCopy
```
1
  cd ios && pod update && cd ..
```

Get an access token

You need an access token to use the location services used in this tutorial.

Go to the Create an API key tutorial to obtain an access token using your ArcGIS Location Platform or ArcGIS Online account.
Ensure that the following privilege is enabled: Location services > Basemaps > Basemap styles service.
Copy the access token as it will be used in the next step.

To learn more about other ways to get an access token, go to Types of authentication.

Set your API key

In VS Code, open lib/main.dart.

Import the arcgis_maps package.

main.dart
Use dark colors for code blocks
2
3
4
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
5
Add line.
import 'package:flutter/material.dart';

import 'package:arcgis_maps/arcgis_maps.dart';

In the main() function, define a const apiKey and set its value with your access token.
main.dart
Use dark colors for code blocks
5 5 5 5 5 6 7 8 9 9 9 10 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11 11
Add line.
```
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
void main() {

  const apiKey = ''; // Your access token here.

  runApp(const MainApp());
}
```
Warning
The access token is stored directly in the code as a convenience for this tutorial. Storing access tokens in the source code is not best practice.
Set the ArcGISEnvironment.apiKey to the apiKey constant.
main.dart
Use dark colors for code blocks
5 5 5 5 5 6 7 8 9 10 11 12 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13 13
Add line.
```
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
void main() {

  const apiKey = ''; // Your access token here.

  ArcGISEnvironment.apiKey = apiKey;

  runApp(const MainApp());
}
```
Attention
If an API Key is required but the access token has not been set (or has been set to an invalid value), you may see the following error when you run the tutorial code:
Unhandled Loadable ArcGISMap load error: ArcGISException: code=22; HttpException: Failed to parse header value.
If you encounter this error, check that a valid access token is set on the ArcGISEnvironment.apiKey property. A known issue in the core Flutter HTTP stack means the ArcGIS Maps SDK for Flutter cannot reliably provide a more descriptive error at this time.

Instantiate MaterialApp inside runApp() and set the named argument, home, to an instance of MainApp.

main.dart
Use dark colors for code blocks
16
16
16
16
16
16
16
16
16
16
16
16
16
16
16
16
17
18
19
20
21
22
22
22
22
22
22
22
22
22
22
22
23
24
25
26
27
28
29
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
30
Change lineChange lineChange linevoid main() {

  const apiKey = ''; // Your access token here.

  ArcGISEnvironment.apiKey = apiKey;

  runApp(

    const MaterialApp(
      home: MainApp(),
    ),

  );
}

Add a map

Create a map that contains a topographic basemap layer. The map will be centered on the Santa Monica Mountains in California.

Refactor the template MainApp class definition to extend StatefulWidget. Hover your mouse over the StatelessWidget keyword, right-click, select Refactor..., and chose Convert to StatefulWidget to refactor your code.

When working with the ArcGIS Maps SDK for Flutter, it is very common to require updates to application state, such as making updates to the UI in response to data changes. By implementing a stateful widget, your app is ready for this. It is also possible to simply display a map using a stateless widget implementation, see the Display map sample.
main.dart
Use dark colors for code blocks
24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47
Change lineChange lineChange lineAdd line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
```
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
class MainApp extends StatefulWidget {

  const MainApp({super.key});

  @override
  State<MainApp> createState() => _MainAppState();

}

class _MainAppState extends State<MainApp> {
  @override
  Widget build(BuildContext context) {

    return const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Hello World!'),
        ),
      ),
    );

  }
}
```

Remove the MaterialApp widget that is returned within the build method. This code was generated by the Flutter create template and will be replaced with code to return a widget that contains a map next.

main.dart
Use dark colors for code blocks
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
Remove lineRemove lineRemove lineRemove lineRemove lineRemove lineRemove lineclass MainApp extends StatefulWidget {

  const MainApp({super.key});

  @override
  State<MainApp> createState() => _MainAppState();

}

class _MainAppState extends State<MainApp> {
  @override
  Widget build(BuildContext context) {

    return const MaterialApp(
      home: Scaffold(
        body: Center(
          child: Text('Hello World!'),
        ),
      ),
    );

  }
}

Inside _MainAppState class define a final class member variable, _mapViewController, and initialize it with ArcGISMapViewController by calling the createController() on the ArcGISMapView class.

The ArcGIS map view controller is a user interface control that displays two-dimensional (2D) geographic content defined by an ArcGISMap.
main.dart
Use dark colors for code blocks
48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 49 50 51 52 53 54 55 55 55 55 55 55 55 55 55 55 55 55 55 55 56 57 57 57 57 57 57 57 57 57 57 57 57 57 57 57 57 58
Add line.
```
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
class _MainAppState extends State<MainApp> {

  final _mapViewController = ArcGISMapView.createController();

  @override
  Widget build(BuildContext context) {

  }

}
```
Within the build method, add an ArcGISMapView widget to the widget tree consisting of Scaffold, Column, and Expanded. Set the named argument, controllerProvider, to the class member variable _mapViewController and the onMapViewReady argument to a new method with the same name as the argument that you will define next.

The Scaffold widget provides a basic material design visual layout structure, while the Column widget displays its children in a vertical array. The ArcGISMapView widget can only be used within a widget that has a bounded size. Using it with unbounded size will cause the application to throw an exception. For example, to use an ArcGISMapView within a Column widget, which would give it unbounded size, would produce such an exception. Instead, you could wrap the ArcGISMapView in an Expanded widget to provide it proper bounds as illustrated in this step of the tutorial.
main.dart
Use dark colors for code blocks
48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 70 70 70 70 70 70 70 70 70 70 70 70 70 70 70 71
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
```
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
class _MainAppState extends State<MainApp> {

  final _mapViewController = ArcGISMapView.createController();

  @override
  Widget build(BuildContext context) {

    return Scaffold(
      body: Column(
        children: [
          Expanded(
            child: ArcGISMapView(
              controllerProvider: () => _mapViewController,
              onMapViewReady: onMapViewReady,
            ),
          ),
        ],
      ),
    );

  }

}
```

Within _MainAppState, define a new method: onMapViewReady() that does not return anything.

main.dart
Use dark colors for code blocks
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
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
72
72
72
72
72
72
72
72
72
72
72
73
74
75
Add line.Add line.Add line.class _MainAppState extends State<MainApp> {

  final _mapViewController = ArcGISMapView.createController();

  @override
  Widget build(BuildContext context) {

    return Scaffold(
      body: Column(
        children: [
          Expanded(
            child: ArcGISMapView(
              controllerProvider: () => _mapViewController,
              onMapViewReady: onMapViewReady,
            ),
          ),
        ],
      ),
    );

  }

  void onMapViewReady() {

  }

}

Within the new method define a final variable, map, and initialize it to an ArcGISMap with the ArcGIS Topographic basemap style.

main.dart
Use dark colors for code blocks
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
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
74
74
74
74
74
74
74
74
74
75
76
77
Add line.class _MainAppState extends State<MainApp> {

  final _mapViewController = ArcGISMapView.createController();

  @override
  Widget build(BuildContext context) {

    return Scaffold(
      body: Column(
        children: [
          Expanded(
            child: ArcGISMapView(
              controllerProvider: () => _mapViewController,
              onMapViewReady: onMapViewReady,
            ),
          ),
        ],
      ),
    );

  }

  void onMapViewReady() {

    final map = ArcGISMap.withBasemapStyle(BasemapStyle.arcGISTopographic);

  }

}

Set the ArcGIS map view controller's arcGISMap property to the map. In addition, call setViewpoint() to zoom to the Santa Monica Mountains in California.

main.dart
Use dark colors for code blocks
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
48
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
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.class _MainAppState extends State<MainApp> {

  final _mapViewController = ArcGISMapView.createController();

  @override
  Widget build(BuildContext context) {

    return Scaffold(
      body: Column(
        children: [
          Expanded(
            child: ArcGISMapView(
              controllerProvider: () => _mapViewController,
              onMapViewReady: onMapViewReady,
            ),
          ),
        ],
      ),
    );

  }

  void onMapViewReady() {

    final map = ArcGISMap.withBasemapStyle(BasemapStyle.arcGISTopographic);

    _mapViewController.arcGISMap = map;
    _mapViewController.setViewpoint(
      Viewpoint.withLatLongScale(
        latitude: 34.02700,
        longitude: -118.80500,
        scale: 72000,
      ),
    );

  }

}

Run the app

Make sure you have an Android emulator, iOS simulator or physical device configured and running.
In VS Code, select Run > Run Without Debugging.

Run download solution

If you have downloaded the project solution, follow these steps to run the application.

Open the extracted project in VS code.
In VS Code's terminal, run:
Use dark colors for code blocksCopy
```
1
  flutter pub upgrade
```
Run:
Use dark colors for code blocksCopy
```
1
  dart run arcgis_maps install
```
Make sure to get an access token and set your API key in the lib/main.dart source code file.
Make sure you have an Android emulator, iOS simulator or physical device configured and running.
In VS Code, select Run > Run Without Debugging.