# Controller

The `mapController` property takes a `MapController`, and whilst it is optional, it is strongly recommended for any map other than the most basic. It allows you to programmatically interact with the map, such as panning, zooming and rotating.

## Initialisation

To use a `MapController`, it must initialised and then passed to the `FlutterMap`. This attaches them until the widget is destroyed/disposed.

```dart
final mapController = MapController();

@override
Widget build(BuildContext context) =>
    FlutterMap(
        mapController: mapController,
        ...
    );
```

## Usage In `initState()`

It is a fairly common requirement to need to use the `MapController` before the map has been built, or to initialise a listener for one of it's streams inside the `initState()` `StatefulWidget` method. Unfortunately, this is not possible, as the map must be built for the controller to be attached.

### Recommended Usage

Luckily, Flutter provides methods to wait until the first frame has been built, which usually means the `FlutterMap` widget will have been built (see exception circumstances below). This makes it trivially easy to implement the desired behaviour.

{% code title="Recommended Usage" %}

```dart
@override
void initState(){
    super.initState();
    WidgetsBinding.instance.addPostFrameCallback((_) {
        // Use `MapController` as needed
    });
}
```

{% endcode %}

### Alternative Usage

{% hint style="info" %}
For simplicity and readability, it is not recommended to use this method unless needed in your situation, although there should be little technical difference.
{% endhint %}

In some cases, the `FlutterMap` widget may not have been built on the first frame - for example when using a `FutureBuilder` around the map.

In this case, an alternative method is required to use the `MapController` on build. This method uses the [Other Options](/v3/usage/options/other-options.md#when-map-ready-onmapready) callback.

{% code title="Alternative Usage" %}

```dart
@override
Widget build(BuildContext context) =>
    FlutterMap(
        mapController: mapController,
        options: MapOptions(
            onMapReady: () {
                // Use `MapController` as needed
            },
        ),
    );
```

{% endcode %}

## Available Methods

{% embed url="<https://pub.dev/documentation/flutter_map/latest/flutter_map/MapController-class.html>" %}
Full API Reference
{% endembed %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fleaflet.dev/v3/usage/controller.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.