@castelio-it/capacitor-mapboxnav

Important

Mapbox Navigation Plugin for Capacitor Robust Turn-by-Turn navigation, Location Tracking, and Free Drive support for Android (iOS coming soon).

capacitor-mapboxnav provides a powerful bridge for the Mapbox Navigation SDK (NDK) for Capacitor apps, allowing you to build professional-grade navigation apps with turn-by-turn guidance.

Install

To use npm

npm install @castelio-it/capacitor-mapboxnav

To use bun

bun add @castelio-it/capacitor-mapboxnav

Sync native files

bunx cap sync 

Android Setup

Mapbox Navigation requires a secret token to download its SDK.

1. Go to your Mapbox account's tokens page.
2. Create a token with the Downloads:Read scope.
3. Add the following to your global ~/.gradle/gradle.properties or to android/gradle.properties in your project:

   MAPBOX_DOWNLOADS_TOKEN=YOUR_SECRET_MAPBOX_ACCESS_TOKEN
   

API

• echo(...)
• initialize(...)
• startNavigation(...)
• startTurnByTurnExperience(...)
• startFreeDrive()

echo(...)

echo(options: { value: string; }) => Promise<{ value: string; }>

Echo back the provided value.

Param	Type
options	{ value: string; }

Returns: Promise<{ value: string; }>

---

initialize(...)

initialize(options: { accessToken: string; }) => Promise<void>

Initialize the Mapbox Navigation SDK with your public access token. This must be called before any navigation activity.

Param	Type
options	{ accessToken: string; }

---

startNavigation(...)

startNavigation(options: { origin: { latitude: number; longitude: number; }; destination: { latitude: number; longitude: number; }; simulateRoute?: boolean; }) => Promise<void>

Start a basic navigation session with a simple map overview. Useful for background navigation or lightweight tracking.

Param	Type
options	{ origin: { latitude: number; longitude: number; }; destination: { latitude: number; longitude: number; }; simulateRoute?: boolean; }

---

startTurnByTurnExperience(...)

startTurnByTurnExperience(options: { origin: { latitude: number; longitude: number; }; destination: { latitude: number; longitude: number; }; simulateRoute?: boolean; }) => Promise<void>

Start a full Turn-by-Turn navigation experience. Includes instruction banners, maneuvers, speed limits, and total trip progress.

Param	Type
options	{ origin: { latitude: number; longitude: number; }; destination: { latitude: number; longitude: number; }; simulateRoute?: boolean; }

---

startFreeDrive()

startFreeDrive() => Promise<void>

Start a Free Drive session (Position tracking). Shows the map centered on the user with no active route or destination.

---

Example

import { capacitormapboxnav } from '@castelio-it/capacitor-mapboxnav';

async function startTurnByTurn() {
  await capacitormapboxnav.initialize({
    accessToken: 'YOUR_PUBLIC_MAPBOX_ACCESS_TOKEN'
  });

  await capacitormapboxnav.startTurnByTurnExperience({
    origin: { latitude: 35.723976, longitude: 10.745365 },
    destination: { latitude: 35.831016, longitude: 10.626204 },
    simulateRoute: true
  });
}