Options

MapOptions is flutter_map's MapOptions, field for field, plus the native additions marked below.

Initial Positioning

initialCenter + initialZoom (+ initialRotation in degrees, clockwise), or initialCameraFit to open on exactly what must be visible. A fit is solved in Dart against the widget's size before the native view is created — the first frame already shows it — and solved again once the map is ready if the size changed in between:

MapOptions(
  initialCameraFit: CameraFit.bounds(bounds: routeBounds, padding: EdgeInsets.all(24)),
)

CameraFit keeps flutter_map's API: CameraFit.bounds (the bounds fit entirely inside the view), CameraFit.insideBounds (nothing outside visible), CameraFit.coordinates (every coordinate visible, honouring the current rotation), or your own subclass. Without a permissions prompt you can also approximate the user's area first and refine later, as with flutter_map.

Permanent Rules

minZoom / maxZoom bound the camera for gestures and MapController calls alike (0 and 22 on the native maps when null). cameraConstraint keeps the camera inside an area:

Constraint	Behaviour
CameraConstraint.containCenter	the center stays inside the bounds — exact natively (Google setLatLngBoundsForCameraTarget, MapKit cameraBoundary)
CameraConstraint.contain	the whole view stays inside — turned into a center boundary recomputed as the camera settles and the zoom changes; during a pinch an edge can show briefly
CameraConstraint.containLatitude	the whole view between two latitudes
a custom subclass	when a gesture ends the camera animates to the constraint's result (or back to the last valid position) — a snap-back, where flutter_map stops the gesture instead

Base map and native settings

mapStyle picks the native base map (standard, satellite, terrain… MapStyle.none hides it, for apps whose TileLayer replaces it) and showsPointsOfInterest toggles the base map's points of interest. Everything else native lives in nativeParams, refined per platform with nativeParams.android / nativeParams.apple:

Field	Effect
showsUserLocation	the platform's own location dot (needs the location permission)
showsCompass / showsBuildings / showsTraffic	the platform's compass, 3D buildings, traffic layer
tiltGestures	two-finger tilt — a tilted camera makes the Dart projections of MapCamera wrong, so use it for the view only
padding	insets the native UI (logo, legal notice, my-location button) without shifting MapCamera.center: the core compensates the shift both SDKs apply

The flutter_map backend ignores nativeParams entirely.

Custom CRSs

Any flutter_map Crs works on the flutter_map backend. The native maps are Web Mercator only: any other value reports MapErrorCode.unsupportedCrs through onMapError (and UnifiedMap.errorBuilder) and the map stays Web Mercator.

Keep Alive

keepAlive: true keeps the native view alive when the map sits in a lazy list or a tab view that would otherwise dispose it.

Lifecycle

• onMapReady — the map accepts controller calls; until then the calls set the camera the map will be created with;
• onMapLoaded — the base map content finished loading (again after a load error, which onMapError reports); MapError codes include apiKeyMissing, servicesUnavailable and loadFailed.