flutter_map Docs
Project Links💝 Support Us
v4
v4
  • flutter_map
  • How Does It Work?
    • Raster vs Vector Tiles
  • Getting Started
    • Installation
    • Additional Setup
    • Examples
    • Migrating To v4
  • Usage
    • Base Widget
    • Options
    • Layers
    • Controller
    • Full API Reference
  • Layers
    • Tile Layer
      • Tile Providers
    • Marker Layer
    • Polygon Layer
    • Polyline Layer
    • Circle Layer
    • Overlay Image Layer
    • Attribution Layer
    • WMS Usage
  • Plugins
    • Plugins List
    • Making A Plugin
      • Creating New Tile Providers
      • Creating New Layers
  • Tile Servers
    • Using Mapbox
    • Using Thunderforest
    • Using Stadia Maps
    • Offline Mapping
    • Other Options
  • Frequently Asked Questions
  • Contributing
  • Credits
Powered by GitBook

© flutter_map Authors & Maintainers

On this page
  • Initial Positioning
  • Permanent Rules
  • Event Handling
  • Through MapController
  • Through MapOptions

Was this helpful?

Export as PDF
  1. Usage

Options

PreviousBase WidgetNextLayers

Last updated 2 years ago

Was this helpful?

To dictate what the map can/should do, regardless of its contents, it needs some guidance!

It provides options that can be categorized into three main parts:

  • Defines the location of the map when it is first loaded

  • Defines restrictions that last throughout the map's lifetime

  • Defines methods that are called on specific map events

Initial Positioning

One part of MapOptions responsibilities is to define how the map should be positioned when first loaded. There's two ways to do this (that are incompatible):

  • center & zoom Defines the center coordinates of the map and a zoom level

  • bounds Defines an area with two/four coordinates that the viewport should fit to

It is possible to also set the map's rotation in degrees, if you don't want it North (0°) facing initially.

Changing these properties after the map has already been built for the first time will have no effect: they only apply on initialisation.

To control the map programatically, use a MapController: Controller.

Permanent Rules

One part of MapOptions responsibilities is to define the restrictions and limitations of the map and what users can/cannot do with it.

  • maxZoom (and minZoom) Limits how far the map can be zoomed by the user, to avoid showing empty tiles

  • maxBounds Limits how far the map can be moved by the user to a coordinate-based boundary

  • keepAlive If FlutterMap is located inside a PageView, ListView or another complex lazy layout, set this true to prevent the map from resetting to the Initial Positioning on rebuild

Instead of maxZoom (or in addition to), consider setting maxNativeZoom per TileLayer instead, to allow tiles to scale (and lose quality) on the final zoom level, instead of setting a hard limit.

Event Handling

When changes happen to FlutterMap's internal state, such as a change to the current position or zoom, it emits an event, some of which can be handled through callbacks, others of which can be handled through listening to a Stream.

If building a custom layer (Creating New Layers), consider using FlutterMapState directly instead.

Through MapController

If you are doing any of the following, setup a MapController, and listen to its mapEventStream instead:

  • Capturing more than a couple of events & using the event's payload/data

  • Needing the events in a single Stream

  • Handling events that aren't available in the callbacks below (Through MapOptions)

Through MapOptions

The following callbacks are available:

  • onTap

  • onLongPress

  • onPositionChanged

  • onPointerDown/onPointerUp/onPointerHover/onPointerCancel

  • onMapEvent (does not expose event data) Prefer Through MapController

You should check , but these are recommended for most maps:

interactiveFlags - see for available options Limits what methods the user can interact with the map through (for example, preventing rotation)

onMapReady Primarily used for a MapController's

all the available options
InteractiveFlag
Controller
Usage In initState()
Initial positioning
Permanent rules
Event handling
MapOptions class - flutter_map library - Dart API
Logo