Headless navigation
Headless navigation uses the navigation engine without NavigationView map chrome. You build your own UI and subscribe to progress, banner, and voice events. The pattern matches headless navigation on Android for native SDKs.
Complete Getting started and Permissions and location before using a session.
Create a session
import {
NavigationSession,
navigationSessionEvents,
createTrip,
createWaypoint,
} from "@trimblemaps/navigation-react-native";
import { useEffect, useState } from "react";
const trip = createTrip(
[
createWaypoint(40.361279, -74.600697, "Origin"),
createWaypoint(40.349542, -74.660237, "Destination"),
],
"Headless route",
);
export function HeadlessScreen() {
const [banner, setBanner] = useState("--");
useEffect(() => {
let session: NavigationSession | null = null;
const subscriptions: { remove: () => void }[] = [];
(async () => {
session = await NavigationSession.create();
subscriptions.push(
navigationSessionEvents.addListener(
"routeProgressChange",
(event) => {
console.log(event.distanceRemaining);
},
session.id,
),
);
subscriptions.push(
navigationSessionEvents.addListener(
"bannerInstruction",
(event) => {
if (event.primaryText) {
setBanner(event.primaryText);
}
},
session.id,
),
);
await session.startNavigation(trip, { shouldSimulateRoute: true });
})().catch(console.error);
return () => {
subscriptions.forEach((s) => s.remove());
session?.destroy().catch(() => undefined);
};
}, []);
return <Text>{banner}</Text>;
}
Session API
| API | Description |
|---|---|
NavigationSession.create()
| Create a native session; returns NavigationSession
|
session.startNavigation(trip, options?)
| Start guidance |
session.stopNavigation()
| Stop guidance |
session.destroy()
| Tear down the session |
navigationSessionEvents.addListener(event, handler, sessionId)
| Subscribe to session events |
Pass session.id as the third argument to addListener so events route to the correct session.
Event names
Common navigationSessionEvents names include routeProgressChange, bannerInstruction, voiceInstruction, and navigationRunning. Payload shapes mirror NavigationView callbacks where applicable. See Navigation events.
When to use headless vs NavigationView
| Approach | Use when |
|---|---|
NavigationView
| You want the standard navigation map and controls |
NavigationSession
| You need a fully custom UI or minimal surface area |