Skip to content

Customizable location puck on navigation maps #33

Closed

Description

@mfazekas

Use case

Apps can't change the location puck on a navigation map (<MapView mapViewImpl={NAVIGATION_MAP_VIEW_IMPL}>). LocationPuck from @rnmapbox/maps is the obvious thing to try, but it doesn't work there: the README lists it under known limitations.

On iOS, RNMBXNavigationMapFactory.swift sets NavigationMapView.puckType to .puck3D(.navigationDefault) whenever the session gets a location and to nil when it loses it, overwriting what LocationPuck set. Unmounting LocationPuck sets the puck to nil, which hides the navigation puck until the next location change.

On Android, RNMBXNavigationMapFactory.kt installs its own NavigationLocationProvider, sets a default 2D puck with course bearing, and toggles location.enabled with guidance. Mounting LocationPuck starts rnmapbox's LocationManager on the same map, and both sides fight over location.enabled and the puck settings.

Proposed API

<NavigationViewport
  puck={{
    visible?: boolean,       // default true while there's a location
    bearingImage?: string,   // image name, as in LocationPuck
    scale?: number | Expression,
    model?: ModelProps,      // 3D puck, LocationPuck's shape
  }}
/>

The prop shapes are reused from LocationPuck. The binding keeps owning the puck and applies the options: on iOS it builds .puck2D(Puck2DConfiguration) or .puck3D(Puck3DConfiguration) instead of .navigationDefault; on Android it builds LocationPuck2D/LocationPuck3D instead of createDefault2DPuck. LocationPuck stays unsupported on navigation maps, and the docs say so.

The alternative is for the binding to step aside when a LocationPuck child is mounted and only feed locations. That needs no new API, but it needs a hook from @rnmapbox/maps to tell the navigation package that a puck component is mounted, LocationPuck must not start its own LocationManager on a navigation map, and apps get LocationPuck's defaults (no course bearing) as soon as they mount it. The puck prop is smaller and keeps the navigation defaults, so that's the plan.

Platforms

iOS, Android

Native SDK API

iOS NavigationMapView.puckType; Android LocationComponentSettings.locationPuck (LocationPuck2D, LocationPuck3D).

Activity

  1. added 2 commits that reference this issue on Oct 29, 2026
    ce863bb
    7e03308
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions