> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/android/navigation/v2/llms.txt)

# Route arrow

The Navigation SDK allows you to display an arrow on a map that illustrates the next maneuver as a user navigates along a route. This is a common UI component used in turn-by-turn navigation applications.

## Use the route maneuver arrow UI component

The route maneuver arrow UI component consists of two main classes:

-   The [`MapboxRouteArrowApi`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route.arrow.api/-mapbox-route-arrow-api/) consumes [`RouteProgress` objects](https://docs.mapbox.com/android/navigation/v2/guides/turn-by-turn-navigation/route-progress/) and calculates an arrow for the next maneuver.
-   The [`MapboxRouteArrowView`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route.arrow.api/-mapbox-route-arrow-view/) class handles consuming the calculated arrow data and rendering an arrow on the map.

By default the route maneuver arrow will be displayed as a white arrow on top of the route line (if it exists) or on top of all features in the map. It will be visible for the maneuver that is next based on the device location.

![A screen shot showing the default style of the route arrow component.](https://docs.mapbox.com/android/assets/ideal-img/navigation-examples-turn-by-turn-experience.c4d072e.480.png)

### Instantiate the route maneuver arrow API

Instantiate the `MapboxRouteArrowApi` and `MapboxRouteArrowView` classes in your `Activity` or `Fragment`.

```kotlin
val routeArrow = MapboxRouteArrowApi()
val routeArrowOptions = RouteArrowOptions.Builder(context).build()
val routeArrowView = MapboxRouteArrowView(routeArrowOptions)
```

To show the next maneuver arrow, register a `RouteProgressObserver` with [`MapboxNavigation`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavigation-core/com.mapbox.navigation.core/-mapbox-navigation/). When a `RouteProgress` object is received, call the `MapboxRouteArrowApi` and pass the result of the arrow calculation to the render method of `MapboxRouteArrowView`.

```kotlin
private val routeProgressObserver = object : RouteProgressObserver {
	override fun onRouteProgressChanged(routeProgress: RouteProgress) {
		val updatedManeuverArrow = routeArrow.addUpcomingManeuverArrow(routeProgress)
		routeArrowView.renderManeuverUpdate(mapStyle, updatedManeuverArrow)
	}
}
```

Be sure to always unregister observers in `onStop()` or `onDestroy()`.

## Customize the route maneuver arrow

There are several ways to customize the route maneuver arrow UI component using [`RouteArrowOptions`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route.arrow.model/-route-arrow-options/).

### Position the route arrow relative to map layers

The map on which you are displaying your route line contains many individual layers (for example, roads, buildings, labels, and more). The route maneuver arrow UI component consists of layers that are added to the map.

> **Note: Position the route line relative to map layers**
> 
> You can read more about the default position of route line layers relative to other map layers and options for cusomtization in the [Route line](https://docs.mapbox.com/android/navigation/v2/guides/ui-components/route-line/#position-the-route-line-relative-to-map-layers) guide.

By default, the maneuver arrow will be placed on top of all the other layers in the map. This is not always the most optimal position for a route arrow because it may appear on top of road labels and other labels on the map. You can specify the route arrow layers' position within all map layers using the [`aboveLayerId`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route.arrow.model/-route-arrow-options/#%5Bcom.mapbox.navigation.ui.maps.route.arrow.model%2FRouteArrowOptions%2FaboveLayerId%2F%23%2FPointingToDeclaration%2F%5D%2FProperties%2F-1537513813) parameter of the `RouteArrowOptions`. When the maneuver arrow layers are created they will be placed above the layer specified by the `aboveLayerId` option.

We recommend [RouteLayerConstants.TOP_LEVEL_ROUTE_LINE_LAYER_ID](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route/-route-layer-constants/-t-o-p_-l-e-v-e-l_-r-o-u-t-e_-l-i-n-e_-l-a-y-e-r_-i-d.html) as a good starting point which will place the route arrows right above the route line.

```kotlin
val routeArrowOptions = RouteArrowOptions.Builder(this)
    .withAboveLayerId(RouteLayerConstants.TOP_LEVEL_ROUTE_LINE_LAYER_ID)
    .build()
```

## Add custom arrows

The Navigation SDK supports displaying multiple arrows on the map. An arrow is defined by a collection of at least two `Point` objects. The arrowhead is placed at the last point in the collection and the direction of the arrowhead is determined by calculating the bearing of the last two points in the collection.

Arrows can be added to and removed from the map before and during navigation. While the next maneuver arrow is managed by the `MapboxRouteArrowApi` class, it is up to you to manage any other arrows you add to the map.

To add a custom arrow, create an arrow using [`ManeuverArrow`](https://docs.mapbox.com/android/navigation/v2/api/2.22.2/libnavui-maps/com.mapbox.navigation.ui.maps.route.arrow.model/-maneuver-arrow/) and add it to the view.

```kotlin
val myArrow = ManeuverArrow(
            	listOf(
                Point.fromLngLat(-122.432034, 37.775755),
                Point.fromLngLat(-122.431229, 37.775865),
                Point.fromLngLat(-122.431293, 37.776255)
            	)
        	)
        	
val result = mapboxArrowApi.addArrow(myArrow)
routeArrowView.render(style, result)	
```

To remove an arrow you've added before:

```kotlin
val result = mapboxArrowApi.removeArrow(myArrow)
routeArrowView.render(style, result)
```