Google Maps in Flutter: Overview
Google Maps in Flutter allows developers to embed interactive maps directly into mobile and web applications. It is commonly used in apps that rely on location-based features such as navigation, delivery tracking, nearby search, or displaying points of interest.
Flutter does not ship with Google Maps by default. Integration is handled through an official plugin that wraps the native Google Maps SDKs for each platform.
The widget relies on Platform Views (often Hybrid Composition on Android) to embed the native map surface directly into the Flutter hierarchy. Unlike standard widgets, the map does not rebuild to update its content. Instead, the Flutter side sends imperative commands via a MethodChannel to the native controller, which modifies the existing native view instance (e.g., moving the camera or adding markers) without destroying or recreating the heavy map object.
Why does Google Maps matter in Flutter app development?
Many real-world applications depend on reliable and interactive maps. Flutter's Google Maps integration makes it possible to build cross-platform location-based features without maintaining separate Android and iOS map implementations.
Using the official plugin provides access to native Google Maps features while keeping a unified Flutter codebase.
How does Google Maps work in Flutter?
Google Maps in Flutter is implemented using platform views.
On Android and iOS, the map is rendered by the native Google Maps SDK. Flutter embeds this view and communicates with it through platform channels to perform actions such as camera movement, marker updates, and gesture handling.
Because of this:
- The map is not rebuilt like standard Flutter widgets.
- Interaction happens through controllers and callbacks.
- Layout constraints must be explicitly defined.
On Flutter Web, the map is rendered using the Google Maps JavaScript API, which behaves differently from mobile platforms.
How to add Google Maps to a Flutter app
Before rendering a map, API keys must be configured correctly.
On Android:
- Create an API key in Google Cloud Console.
- Enable Maps SDK for Android.
- Add the key to
AndroidManifest.xml.
On iOS:
- Enable Maps SDK for iOS.
- Provide the API key in
AppDelegate.
A common beginner issue is seeing a blank map with only the Google logo. This usually means the API key exists, but the correct SDK (Android or iOS) is not enabled in Google Cloud Console. Each platform must be enabled separately.
Flutter Google Maps example
A minimal example displaying a map centered on a fixed location:
GoogleMap(
initialCameraPosition: const CameraPosition(
target: LatLng(52.2297, 21.0122),
zoom: 12,
),
onMapCreated: (controller) {
// GoogleMapController is available here
},
)
The initialCameraPosition defines where the map starts, but it does not allow moving the map later.
Controlling the map with GoogleMapController
To move or animate the map after it has been created, a GoogleMapController is required.
The controller is provided in the onMapCreated callback. This is the moment when the map becomes fully interactive and ready to be controlled programmatically, for example when implementing a "Find my location" button.
Markers and interaction
Markers are used to represent locations such as destinations or points of interest.
Most dynamic behavior is implemented by:
- Updating markers.
- Animating the camera.
- Reacting to user gestures and callbacks.
Navigation-like behavior is achieved by controlling the camera and drawing overlays, not by rebuilding the map widget.
Flutter Google Maps navigation
The Google Maps Flutter plugin does not include built-in turn-by-turn navigation.
It supports:
- Drawing routes using polylines.
- Displaying the user’s current location.
- Updating the camera along a path.
Full navigation requires external services such as the Google Directions API and custom logic.
Google Maps on Flutter Web
Flutter Web uses a different rendering approach than mobile platforms.
Key differences:
- Reduced feature parity compared to Android and iOS.
- Performance depends on the browser.
- API keys must explicitly allow web usage.
Web support works well for basic map display but should be tested carefully for interactive use cases.
On Android:
- Google Play Services are required.
- Emulators must include Play Services to render maps correctly.
On iOS:
- Google Maps relies on platform views.
- The
Info.plist file must include:
io.flutter.embedded_views_preview = YES
Without this flag, the map may fail to render or cause runtime issues on iPhones.
Common mistakes with Google Maps in Flutter
Common issues encountered by developers include:
- API keys without enabled Maps SDK for the target platform.
- Missing platform view configuration on iOS.
- Placing the map inside widgets with unbounded height.
- Rebuilding the map instead of controlling it via
GoogleMapController. - Expecting built-in navigation functionality.
Practical considerations for Google Maps in Flutter
Google Maps in Flutter should be treated as a native view embedded inside a Flutter layout.
In practice:
- Layout constraints must be planned carefully.
- Camera control should be handled through the controller.
- Platform differences between Android, iOS, and Web must be accounted for.
- Routing and location logic should live outside the map widget.
In most applications, the map acts as a visual layer rather than the owner of business logic.
