GuidesKB Articles
Guides
  1. Getting Started

Custom polyline cannot overlay the active navigation route in HERE SDK Navigate 4.25.x

Summary
-------

In HERE SDK Navigate 4.25.4 and 4.25.5, a custom MapPolyline (or equivalent polyline overlay) may not render above the active navigation route once guidance has started with VisualNavigator, even if you set a higher drawOrder (or configure routeDrawOrder / routeDrawOrderType). This is a known behavior/issue where draw-order settings for the route rendering are ineffective in 4.25.x.

Workaround: Use a headless navigation approach (use Navigator instead of VisualNavigator rendering) and draw the route yourself as your own MapPolyline so you fully control rendering order. The official Developer Guides explicitly describe that you can start guidance either with a headless Navigator or with VisualNavigator.

---

Applies to
----------

HERE SDK Navigate for Android and iOS
 Versions: 4.25.4, 4.25.5
Scenario: VisualNavigator guidance started (startRendering(...) / route assigned), then adding a custom polyline overlay

---

Symptoms
--------

You draw a polyline (for example, a highlighted path in yellow), but the active navigation route (blue) still appears on top, so the custom polyline cannot visually cover it. This persists even when:

 Custom polyline draw order is set high (e.g., 100)
VisualNavigator route draw order and draw order type are configured

---

How to reproduce (example)
--------------------------

1. Add a MapPolyline and set its draw order to a high value (for example, 100).
2. Configure navigator draw order settings (for example: root draw order 0; root draw order type MAP_SCENE_ADDITION_ORDER_INDEPENDENT).
3. Start guidance (assign a route to the navigator and start navigation rendering).
4. Observe that the custom polyline still cannot overlay the active navigation route.

---

Cause
-----

In 4.25.x, route rendering in VisualNavigator is affected by changes that make route draw-order controls ineffective. An internal defect report states that the routeDrawOrder and routeDrawOrderType properties "don’t work since 4.25.1" because the underlying implementation was changed to render the route differently, and therefore those properties no longer affect the result.

Separately, there are reports that DrawOrderType changes do not reliably change stacking order in the navigation scenario.

> Practical implication: In active guidance with VisualNavigator, you may not be able to force a custom polyline above the navigation route via draw-order settings alone in 4.25.x.

---

Resolution / Fix status
-----------------------

At the time of writing, there is no configuration-only fix in 4.25.4/4.25.5 that guarantees a custom MapPolyline can overlay the active route rendered by VisualNavigator.

---

Workaround (recommended): Headless guidance + draw the route yourself
---------------------------------------------------------------------

The HERE SDK documentation describes two approaches to start guidance:

 Headless Navigator (render everything yourself)
VisualNavigator (SDK renders navigation view)

To guarantee your own polyline can overlay anything else, use headless guidance and add your own MapPolyline for the route.

### Workaround A — Android (Kotlin) sample

> Note: The following is sample workaround code intended to illustrate the approach. It is not an SDK patch.

<br />// 1) Calculate a Route (RoutingEngine usage omitted for brevity).// Assume you already have: val route: Route// 2) Draw YOUR route polyline with a high draw order.val routeGeometry = route.geometryval rep = MapPolyline.SolidRepresentation( MapMeasureDependentRenderSize.withSingleSize( RenderSizeUnit.PIXELS, 14.0 ), Color.valueOf(1f, 1f, 0f, 1f) // yellow)val myRoutePolyline = MapPolyline(routeGeometry, rep)myRoutePolyline.drawOrder = 100 // keep it highmyRoutePolyline.drawOrderType = DrawOrderType.MAP_SCENE_ADDITION_ORDER_DEPENDENTmapView.mapScene.addMapPolyline(myRoutePolyline)// 3) Start HEADLESS guidance using Navigator (not VisualNavigator rendering).// Pseudocode: use Navigator to receive progress/events but don't let SDK render the route.// val navigator = Navigator()// navigator.route = route// navigator.routeProgressListener = ...// locationProvider.addListener(navigator)<br />

Why this works: you control the rendering order because the visible route line is your MapPolyline. The SDK still provides guidance logic via Navigator, but does not impose VisualNavigator route rendering. The SDK guides explicitly support starting guidance with a headless Navigator instead of VisualNavigator.

For additional reference implementations, HERE provides example apps in the public SDK examples repository.

### Workaround B — iOS (Swift) sample

> Note: The following is sample workaround code intended to illustrate the approach. It is not an SDK patch.

<br />// 1) Calculate a Route (RoutingEngine usage omitted for brevity).// Assume you already have: let route: Route// 2) Draw YOUR route polyline with high draw order.let geometry = route.geometrylet width = MapMeasureDependentRenderSize(measureKind: .zoomLevel, sizeUnit: .pixels, sizes: [0: 14])let rep = try MapPolyline.SolidRepresentation(renderSize: width, color: .init(red: 1, green: 1, blue: 0, alpha: 1))let myRoutePolyline = MapPolyline(geometry: geometry, representation: rep)myRoutePolyline.drawOrder = 100myRoutePolyline.drawOrderType = .mapSceneAdditionOrderDependentmapView.mapScene.addMapPolyline(myRoutePolyline)// 3) Start HEADLESS guidance using Navigator (not VisualNavigator rendering).// Pseudocode:// let navigator = Navigator()// navigator.route = route// navigator.routeProgressDelegate = ...// locationProvider.addDelegate(navigator)<br />

Again, the core idea is: don’t rely on VisualNavigator to render the route if you must guarantee overlay order. The iOS guide also documents the headless-vs-visual split.

---

Notes / Tradeoffs
-----------------

 Using headless guidance means you may need to implement your own visual elements (route styling, maneuver arrows, etc.) that VisualNavigator would otherwise render automatically. The SDK guides describe that VisualNavigator provides "visual rendering assistance", while headless navigation is available if you want full control.
If your application must keep VisualNavigator rendering for other reasons, then overlaying above the active route may not be achievable in 4.25.x using draw-order settings alone.

---

References (customer-facing)
----------------------------

 HERE SDK navigation overview / guidance options (headless Navigator vs VisualNavigator): docs.here.com navigation
Android "Build a navigation app" tutorial: navigation app tutorial
 iOS "Build a navigation app" tutorial: navigation app tutorial (iOS)
HERE SDK 4.x Examples repository (Android/iOS/Flutter): here-sdk-examples on GitHub
 (If you want to mention API properties) Flutter API refs for route/polyline draw ordering:
+ routeDrawOrderType: VisualNavigator.routeDrawOrderType
+ MapPolyline.drawOrderType: MapPolyline.drawOrderType

---

Tags
----

HERE SDK, Navigate Edition, Android, iOS, VisualNavigator, Navigator, MapPolyline, drawOrder, routeDrawOrder, rendering order, polyline overlay