# Get started with maps

Last updated:

<!-- -->

October 18, 2026

<!-- -->

\| 2 minutes read

<br />

<br />

Learn how to display a map view and use the `GemMapController` to enable additional map functionalities.

## Display a map[​](#display-a-map "Direct link to Display a map")

The `GemMap` widget, a subclass of `StatefulWidget`, provides powerful mapping capabilities with a wide range of configurable options. The following code demonstrates how to display a map view in your `main.dart` file:

```dart
import 'package:flutter/material.dart';

import 'package:magiclane_maps_flutter/core.dart';
import 'package:magiclane_maps_flutter/map.dart';

const projectApiToken = String.fromEnvironment('YOUR_API_TOKEN_HERE');

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return const MaterialApp(
      debugShowCheckedModeBanner: false,
      title: 'Hello Map',
      home: MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  @override
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  @override
  void dispose() {
    GemKit.release();
    super.dispose();
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        backgroundColor: Colors.deepPurple[900],
        title: const Text('Hello Map', style: TextStyle(color: Colors.white)),
      ),
      body: const GemMap(
        appAuthorization: projectApiToken,
        onMapCreated: _onMapCreated,
      ),
    );
  }

  void _onMapCreated(GemMapController mapController) {
    // Code executed when the map is initialized
  }
}

```

Paste your API token in place of `YOUR_API_TOKEN_HERE`, in between the qoutes for a quick start. Note that it is recommended to store the API token securely, such as in environment variables or secure storage, rather than hardcoding it in the source code for production applications. Keep in mind that the token has an expiration date, so please ensure to update it before it expires to maintain uninterrupted access to the services.

![Displaying a default day map](/docs/flutter/assets/images/example_flutter_hello_map1-bdb5edaa18b263ef6f5eca72726c2f8c.png)

**Displaying a default day map**

## Use the map controller[​](#use-the-map-controller "Direct link to Use the map controller")

The `GemMap` widget includes an `onMapCreated` callback, which is triggered once the map has finished initializing. This callback provides a `GemMapController` to enable additional map functionalities.

```dart
const GemMap(
  appAuthorization: projectApiToken,
  onMapCreated: _onMapCreated,
),

```

Tip

Multiple `GemMap` widgets can be instantiated within a single application, allowing you to display different data on each map. Each `GemMap` is independently controlled via its respective `GemMapController`.

Certain settings, such as language, overlay visibility, and position tracking, are shared across all `GemMap` instances within the application.

## Relevant examples demonstrating map related features[​](#relevant-examples-demonstrating-map-related-features "Direct link to Relevant examples demonstrating map related features")

* [Map Compass](/docs/flutter/examples/maps-3dscene/map-compass.md)
* [Map Perspective](/docs/flutter/examples/maps-3dscene/map-perspective.md)
* [Map Gestures](/docs/flutter/examples/maps-3dscene/map-gestures.md)
* [Map Styles](/docs/flutter/examples/maps-3dscene/map-styles.md)
* [Multiview Map](/docs/flutter/examples/maps-3dscene/multiview-map.md)
* [Overlapped Maps](/docs/flutter/examples/maps-3dscene/overlapped-maps.md)
* [Center Coordinates](/docs/flutter/examples/maps-3dscene/center-coordinates.md)
* [Landmarks Selection](/docs/flutter/examples/maps-3dscene/map-selection.md)
* [Display Cursor Street Name](/docs/flutter/examples/places-search/display-cursor-street.md)
* [Assets Map Style](/docs/flutter/examples/maps-3dscene/assets-map-styles.md)