{"id":19920611,"url":"https://github.com/mapbox/mapbox-maps-flutter","last_synced_at":"2026-02-25T17:29:57.550Z","repository":{"id":65041526,"uuid":"543031087","full_name":"mapbox/mapbox-maps-flutter","owner":"mapbox","description":"Interactive, thoroughly customizable maps for Flutter powered by Mapbox Maps SDK","archived":false,"fork":false,"pushed_at":"2026-02-11T12:13:59.000Z","size":95642,"stargazers_count":362,"open_issues_count":343,"forks_count":184,"subscribers_count":84,"default_branch":"main","last_synced_at":"2026-02-11T20:26:26.669Z","etag":null,"topics":["dart","flutter","map","mapbox","maps","priority"],"latest_commit_sha":null,"homepage":"https://www.mapbox.com/mobile-maps-sdk","language":"Dart","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mapbox.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2022-09-29T09:24:27.000Z","updated_at":"2026-02-02T09:58:58.000Z","dependencies_parsed_at":"2023-10-03T16:37:50.389Z","dependency_job_id":"e08cf6a1-3ab7-424f-ab3d-eaaf9fc68c06","html_url":"https://github.com/mapbox/mapbox-maps-flutter","commit_stats":{"total_commits":339,"total_committers":11,"mean_commits":"30.818181818181817","dds":"0.38348082595870203","last_synced_commit":"708284820eb3b065d0c0a9628bedabecf6eafd26"},"previous_names":[],"tags_count":81,"template":false,"template_full_name":null,"purl":"pkg:github/mapbox/mapbox-maps-flutter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fmapbox-maps-flutter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fmapbox-maps-flutter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fmapbox-maps-flutter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fmapbox-maps-flutter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mapbox","download_url":"https://codeload.github.com/mapbox/mapbox-maps-flutter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mapbox%2Fmapbox-maps-flutter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29832965,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-25T17:17:09.781Z","status":"ssl_error","status_checked_at":"2026-02-25T17:16:50.421Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dart","flutter","map","mapbox","maps","priority"],"created_at":"2024-11-12T22:05:16.246Z","updated_at":"2026-02-25T17:29:57.544Z","avatar_url":"https://github.com/mapbox.png","language":"Dart","readme":"# Mapbox Maps SDK Flutter SDK\n\nThe Mapbox Maps SDK Flutter SDK is an officially developed solution from Mapbox that enables use of our latest Maps SDK product (v11.19.0-beta.1). The SDK allows developers to embed highly-customized maps using a Flutter widget on Android and iOS.\n\nWeb and desktop are not supported.\n\nContributions welcome!\n\n## Supported API\n\n| Feature | Android            | iOS |\n| ------ |--------------------| -- |\n| Style | :white_check_mark: | :white_check_mark: |\n| Camera position | :white_check_mark: | :white_check_mark: |\n| Camera animations | :white_check_mark: | :white_check_mark: |\n| Events | :white_check_mark: | :white_check_mark: |\n| Gestures | :white_check_mark: | :white_check_mark: |\n| User Location | :white_check_mark: | :white_check_mark: |\n| Circle Layer | :white_check_mark: | :white_check_mark: |\n| Fill Layer | :white_check_mark: | :white_check_mark: |\n| Fill extrusion Layer | :white_check_mark: | :white_check_mark: |\n| Line Layer | :white_check_mark: | :white_check_mark: |\n| Circle Layer | :white_check_mark: | :white_check_mark: |\n| Raster Layer  | :white_check_mark: | :white_check_mark: |\n| Symbol Layer | :white_check_mark: | :white_check_mark: |\n| Hillshade Layer | :white_check_mark: | :white_check_mark: |\n| Heatmap Layer   | :white_check_mark: | :white_check_mark: |\n| Sky Layer | :white_check_mark: | :white_check_mark: |\n| GeoJson Source  | :white_check_mark: | :white_check_mark: |\n| Image Source   | :white_check_mark: | :white_check_mark: |\n| Vector Source   | :white_check_mark: | :white_check_mark: |\n| Raster Source  | :white_check_mark: | :white_check_mark: |\n| Rasterdem Source  | :white_check_mark: | :white_check_mark: |\n| Circle Annotations | :white_check_mark: | :white_check_mark: |\n| Point Annotations | :white_check_mark: | :white_check_mark: |\n| Line Annotations | :white_check_mark: | :white_check_mark: |\n| Fill Annotations | :white_check_mark: | :white_check_mark: |\n| Snapshotter | :white_check_mark: | :white_check_mark: |\n| Offline | :white_check_mark: | :white_check_mark: |\n| Viewport | :white_check_mark: | :white_check_mark: |\n| Style DSL   | :x:                | :x: |\n| Expression DSL   | :x:                | :x: |\n| View Annotations   | :x:                | :x: |\n\n## Requirements\n\nThe Maps Flutter SDK is compatible with applications:\n\n- Deployed on iOS 14 or higher\n- Built using the Android SDK 21 or higher\n- Built using the Flutter SDK 3.22.3/Dart SDK 3.4.4 or higher\n\n## Installation\n\n### Configure credentials\nTo run the Maps Flutter SDK you will need to configure the Mapbox Access Token.\nRead more about access tokens in the platform [Android](https://docs.mapbox.com/android/maps/guides/install/#configure-credentials) or [iOS](https://docs.mapbox.com/ios/maps/guides/install/#step-4-configure-your-public-token) docs.\n\n#### Access token\nYou can set the access token for Mapbox Maps Flutter SDK(as well as for every Mapbox SDK) via `MapboxOptions`:\n```\n  MapboxOptions.setAccessToken(ACCESS_TOKEN);\n```\n\nIt's a good practice to retrieve the access token from some external source.\n\nYou can pass access token via the command line arguments when either building :\n\n```\nflutter build \u003cplatform\u003e --dart-define ACCESS_TOKEN=...\n```\n\nor running the application :\n\n```\nflutter run --dart-define ACCESS_TOKEN=...\n```\n\nYou can also persist token in launch.json :\n```\n\"configurations\": [\n    {\n        ...\n        \"args\": [\n            \"--dart-define\", \"ACCESS_TOKEN=...\"\n        ],\n    }\n]\n```\n\nThen to retrieve the token from the environment in the application :\n```\nString ACCESS_TOKEN = String.fromEnvironment(\"ACCESS_TOKEN\");\n```\n\n### Configure permissions\nYou will need to grant location permission in order to use the location component of the Maps Flutter SDK.\n\nYou can use an existing library to request location permission, e.g. with [permission_handler](https://pub.dev/packages/permission_handler) `await Permission.locationWhenInUse.request();` will trigger permission request.\n\nYou also need to declare the permission for both platforms :\n\n#### Android\nAdd the following permissions to the manifest:\n```\n    \u003cuses-permission android:name=\"android.permission.ACCESS_FINE_LOCATION\" /\u003e\n    \u003cuses-permission android:name=\"android.permission.ACCESS_COARSE_LOCATION\" /\u003e\n```\n\n#### iOS\nAdd the following key/value pair to the `Runner/Info.plist`. In the value field, explain why you need access to location:\n\n```\n    \u003ckey\u003eNSLocationWhenInUseUsageDescription\u003c/key\u003e\n    \u003cstring\u003e[Your explanation here]\u003c/string\u003e\n```\n\n### Add a map\nImport `mapbox_maps_flutter` library and add a simple map:\n```\nimport 'package:flutter/material.dart';\nimport 'package:mapbox_maps_flutter/mapbox_maps_flutter.dart';\n\nvoid main() {\n  runApp(MaterialApp(home: MapWidget()));\n}\n```\n\n#### MapWidget widget\nThe `MapWidget` widget provides options to customize the map - you can set `MapOptions`, `CameraOptions`, `styleURL`, etc.\n\nYou can also add listeners for various events related to style loading, map rendering, map loading.\n\n#### MapboxMap controller\nThe `MapboxMap` controller instance is provided with `MapWidget.onMapCreated` callback.\n\n`MapboxMap` exposes an entry point to the most of the APIs Maps Flutter SDK provides. It allows to control the map, camera, styles, observe map events,\nquery rendered features, etc.\n\nIt's organized similarly to the [Android](https://docs.mapbox.com/android/maps/api/11.11.0/mapbox-maps-android/com.mapbox.maps/-mapbox-map/) and [iOS](https://docs.mapbox.com/ios/maps/api/11.11.0/documentation/mapboxmaps/mapboxmap) counterparts.\n\nTo interact with the map after it's created store the MapboxMap object somewhere :\n```\nclass FullMap extends StatefulWidget {\n  const FullMap();\n\n  @override\n  State createState() =\u003e FullMapState();\n}\n\nclass FullMapState extends State\u003cFullMap\u003e {\n  MapboxMap? mapboxMap;\n\n  _onMapCreated(MapboxMap mapboxMap) {\n    this.mapboxMap = mapboxMap;\n  }\n\n  @override\n  Widget build(BuildContext context) {\n    return new Scaffold(\n        body: MapWidget(\n      key: ValueKey(\"mapWidget\"),\n      onMapCreated: _onMapCreated,\n    ));\n  }\n}\n```\n\n## User location\nTo observe the user's location and show the location indicator on the map use `LocationComponentSettingsInterface` accessible via `MapboxMap.location`.\n\nFor more information, please see the User Location guides in our [Flutter](https://docs.mapbox.com/flutter/maps/guides/user-location), [Android](https://docs.mapbox.com/android/maps/guides/user-location/), and [iOS](https://docs.mapbox.com/ios/maps/guides/user-location/) documentation.\n\nYou need to grant location permission prior to using location component (as explained [before](#configure-permissions)).\n\n### Location puck\nTo customize the appearance of the location puck call `MapboxMap.location.updateSettings` method.\n\nTo use the 3D puck with model downloaded from Uri instead of the default 2D puck:\n\n```\n  mapboxMap.location.updateSettings(LocationComponentSettings(\n      locationPuck: LocationPuck(\n          locationPuck3D: LocationPuck3D(\n              modelUri:\n                  \"https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/Duck/glTF-Embedded/Duck.gltf\",))));\n```\n\nYou can find more examples of customization in the sample [app](example/lib/location_example.dart).\n\n## Markers and annotations\nAdditional information is available in our [Flutter](https://docs.mapbox.com/flutter/maps/guides/markers-and-annotations/), [Android](https://docs.mapbox.com/android/maps/guides/annotations/), and [iOS](https://docs.mapbox.com/ios/maps/guides/annotations/) documentation.\n\nYou have several options to add annotations on the map.\n\n1. Use the AnnotationManager APIs to create circle, point, polygon, and polyline annotations.\n\nTo create 5 point annotations using custom icon:\n```\n  mapboxMap.annotations.createPointAnnotationManager().then((pointAnnotationManager) async {\n    final ByteData bytes =\n        await rootBundle.load('assets/symbols/custom-icon.png');\n    final Uint8List list = bytes.buffer.asUint8List();\n    var options = \u003cPointAnnotationOptions\u003e[];\n    for (var i = 0; i \u003c 5; i++) {\n      options.add(PointAnnotationOptions(\n          geometry: Point.fromJson(createRandomPoint().toJson()), image: list));\n    }\n    pointAnnotationManager.createMulti(options);\n  });\n```\nYou can find more examples of the AnnotationManagers usage in the sample app : [point annotations](example/lib/point_annotations.dart), [circle annotations](example/lib/circle_annotations.dart), [polygon annotations](example/lib/polygon_annotations.dart), [polyline annotations](example/lib/polyline_annotations.dart).\n\n1. Use style layers. This will require writing more code but is more flexible and provides better performance for the large amount of annotations (e.g. hundreds and thousands of them). More about adding style layers in the [Map styles section](#map-styles).\n\n## Map styles\nAdditional information is available in our [Flutter](https://docs.mapbox.com/flutter/maps/guides/styles/), [Android](https://docs.mapbox.com/android/maps/guides/styles/), and [iOS](https://docs.mapbox.com/ios/maps/guides/styles/) documentation.\n\nThe Mapbox Maps Flutter SDK allows full customization of the look of the map used in your application.\n\n### Set a style\nYou can specify the initial style uri at `MapWidget.styleUri`, or load it at runtime using `MapboxMap.loadStyleURI` / `MapboxMap.loadStyleJson`:\n\n```\nmapboxMap.loadStyleURI(Styles.LIGHT);\n```\n\n### Work with layers\nYou can familiarize with the concept of sources, layers and their supported types in the documentation for [Flutter](https://docs.mapbox.com/flutter/maps/guides/styles/work-with-layers), [iOS](https://docs.mapbox.com/ios/maps/guides/styles/work-with-layers/), and [Android](https://docs.mapbox.com/android/maps/guides/styles/work-with-layers/).\n\nTo add, remove or change a source or a layer, use the `MapboxMap.style` object.\n\nTo add a `GeoJsonSource` and a `LineLayer` using the source :\n```\n  var data = await rootBundle.loadString('assets/polyline.geojson');\n  await mapboxMap.style.addSource(GeoJsonSource(id: \"line\", data: data));\n  await mapboxMap.style.addLayer(LineLayer(\n      id: \"line_layer\",\n      sourceId: \"line\",\n      lineJoin: LineJoin.ROUND,\n      lineCap: LineCap.ROUND,\n      lineOpacity: 0.7,\n      lineColor: Colors.red.value,\n      lineWidth: 8.0));\n```\n\n### Using expressions\nYou can change the appearance of a layer based on properties in the layer's data source or zoom level.\nRefer to the [documentation](https://docs.mapbox.com/mapbox-gl-js/style-spec/expressions/) for the description of supported expressions. You can also learn more in the documentation for [Flutter](https://docs.mapbox.com/flutter/maps/guides/styles/style-layers#work-with-expressions), [iOS](https://docs.mapbox.com/ios/maps/guides/styles/style-layers/#work-with-expressions), and [Android](https://docs.mapbox.com/android/maps/guides/styles/style-layers/#work-with-expressions).\n\nTo apply an expression to interpolate gradient color to a line layer:\n```\n  mapboxMap.style.setStyleLayerProperty(\"layer\", \"line-gradient\",\n      '[\"interpolate\",[\"linear\"],[\"line-progress\"],0.0,[\"rgb\",6,1,255],0.5,[\"rgb\",0,255,42],0.7,[\"rgb\",255,252,0],1.0,[\"rgb\",255,30,0]]');\n```\n\n## Camera and animations\nPlatform docs: [Android](https://docs.mapbox.com/android/maps/guides/camera-and-animation/), [iOS](https://docs.mapbox.com/ios/maps/guides/camera-and-animation/).\n\nThe camera is the user's viewpoint above the map. The Maps Flutter SDK provides you with options to set and adjust the camera position, listen for camera changes, get the camera position, and restrict the camera position to set bounds.\n\n### Camera position\nYou can set the starting camera position using `MapWidget.cameraOptions`:\n\n```\nMapWidget(\n  key: ValueKey(\"mapWidget\"),\n  cameraOptions: CameraOptions(\n      center: Point(coordinates: Position(-80.1263, 25.7845)).toJson(),\n      zoom: 12.0),\n));\n```\n\nor update it at runtime using `MapboxMap.setCamera` :\n\n```\nMapboxMap.setCamera(CameraOptions(\n  center: Point(coordinates: Position(-80.1263, 25.7845)).toJson(),\n  zoom: 12.0));\n```\n\nYou can find more examples of interaction with the camera in the sample [app](example/lib/camera.dart).\n\n### Camera animations\nCamera animations are the means by which camera settings are changed from old values to new values over a period of time. You can animate the camera using `flyTo` or `easeTo` and move to a new center location, update the bearing, pitch, zoom, padding, and anchor.\n\nTo start a `flyTo` animation to the specific camera options :\n```\n  mapboxMap?.flyTo(\n    CameraOptions(\n        anchor: ScreenCoordinate(x: 0, y: 0),\n        zoom: 17,\n        bearing: 180,\n        pitch: 30),\n    MapAnimationOptions(duration: 2000, startDelay: 0));\n```\nYou can find more examples of animations in the sample [app](example/lib/animation.dart).\n\n## User interaction\nPlatform docs: [Android](https://docs.mapbox.com/android/maps/guides/user-interaction/), [iOS](https://docs.mapbox.com/ios/maps/guides/user-interaction/).\n\nUsers interacting with the map in your application can explore the map by performing standard gestures.\n\nYou can retrieve or update the `GestureSettings` using `MapboxMap.gestures`.\n\nYou can observe gesture events using `MapWidget.onTapListener`, `MapWidget.onLongTapListener`, `MapWidget.onScrollListener`.\n","funding_links":[],"categories":["Dart"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fmapbox-maps-flutter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmapbox%2Fmapbox-maps-flutter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmapbox%2Fmapbox-maps-flutter/lists"}