The Mapbox Annotation Plugin simplifies the way to set and adjust the visual properties of annotations on a Mapbox map. The Mapbox Maps SDK for Android provides you with fine-grained control over the appearance and location of map annotations.

In this context, "annotations" means circles, polygons, lines, text, and icons. Using runtime and data-driven styling to create annotations can require a deep understanding of the Mapbox Maps SDK. This plugin obfuscates much of the required boilerplate code.

Note: A SymbolLayer is the style layer that is responsible for both map text and icons.

Install the Annotation Plugin

To start developing an application using the Annotation Plugin, you'll need to add the appropriate dependencies inside of your build.gradle. The Annotation Plugin dependency includes the Mapbox Maps SDK for Android. You can find all dependencies given below on MavenCentral.

If your application is close or exceeds the 65k method count limit, you can mitigate this problem by enabling ProGuard inside your application. ProGuard directives are included in the Android dependencies to preserve the required classes.

Add the dependency

  1. Start Android Studio.
  2. Open up your application's build.gradle.
  3. Make sure that your project's minSdkVersion is API 14 or higher.
  4. Under dependencies, add a new build rule for the latest mapbox-android-plugin-annotation-v9.
  5. Click the Sync Project with Gradle Files near the toolbar in Studio.
repositories {

dependencies {
  implementation 'com.mapbox.mapboxsdk:mapbox-android-plugin-annotation-v9:0.9.0'

Initialize the plugin

The plugin includes manager classes for the various map layers available in the Mapbox Maps SDK for Android. The manager classes are explained below and their constructors only require a MapboxMap object. You should initialize a manager class within the onMapReady() method to be sure that the annotations are added to a MapboxMap that's completely ready.

public void onMapReady(@NonNull final MapboxMap mapboxMap) {
mapboxMap.setStyle(Style.MAPBOX_STREETS, new Style.OnStyleLoaded() {
public void onStyleLoaded(@NonNull Style style) {
// Use a layer manager here


The circle, line, fill, and symbol map layers have accompanying manager classes. Each manager class has methods for setting layer properties that are less related to the visual styling. For example, SymbolManager adjusts the position of the SymbolLayer's icon or text with methods such as iconAllowOverlap() or iconTranslate().

You can also set onClick and onLongClick listeners to the type of annotations that you're adding to the map.

Layer typeManager class

For example, here's how a SymbolManager would be used. Don't forget that the code below is running inside of the onStyleLoaded() callback as described in the plugin initialization section above:

// create symbol manager object
SymbolManager symbolManager = new SymbolManager(mapView, mapboxMap, style);
// add click listeners if desired
symbolManager.addClickListener(symbol ->
symbolManager.addLongClickListener(symbol -> {
// set non-data-driven properties, such as:
symbolManager.setIconTranslate(new Float[]{-4f,5f});
Manager class usage

See more usage of various manager classes.


The CircleManager, FillManager, and SymbolManager objects can also create annotations via respective CircleOptions(), FillOptions(), and SymbolOptions() classes. The options classes follow the builder pattern, which allows you to set various layer properties that are more related to visual styling. For example, FillOptions adjusts the look of a FillLayer polygon with methods such as withFillColor(), withFillOpacity(), and withFillPattern().

Layer typeOption class

Creating a Symbol annotation with a SymbolManager and SymbolOptions:

SymbolManager symbolManager = new SymbolManager(mapView, mapboxMap, style);
// Add symbol at specified lat/lon
Symbol symbol = symbolManager.create(new SymbolOptions()
.withLatLng(new LatLng(60.169091, 24.939876))

Creating a Polygon annotation with a FillManager and FillOptions:

// create a fixed fill
List<LatLng> innerLatLngs = new ArrayList<>();
innerLatLngs.add(new LatLng(-10.733102, -3.363937));
innerLatLngs.add(new LatLng(-19.716317, 1.754703));
innerLatLngs.add(new LatLng(-21.085074, -15.747196));
List<List<LatLng>> latLngs = new ArrayList<>();
FillOptions fillOptions = new FillOptions()
// random add fills across the globe
List<FillOptions> fillOptionsList = new ArrayList<>();
for (int i = 0; i < 20; i++) {
int color = Color.argb(255, random.nextInt(256), random.nextInt(256), random.nextInt(256));
fillOptionsList.add(new FillOptions()
Manager class usage

See more usage of various option classes.

As you saw above, the FillManager#create() method takes in a single FillOptions object as a parameter. A List<> of FillOptions is also a valid parameter for the create() method. This is the same for all the manager classes. LineManager will require a LineOptions class and so on.


The CircleManager, FillManager, and SymbolManager objects also expose several listeners for user interaction. addClickListener(), addLongClickListener(), and addDragListener() can all be set on any manager class object.

symbolManager.addClickListener(new OnSymbolClickListener() {
public boolean onAnnotationClick(Symbol symbol) {
Symbol listener

See how to set a click, long click, and drag listener on an Annotation Plugin symbol.