CoPilot Native Nav SDK

Turn-by-turn navigation

Contents

Use NavigationView for the full turn-by-turn experience: map, maneuver banners, voice guidance, and rerouting. Complete Getting started first (packages, native setup, and account licensing).

Build a trip

A trip combines stops, an optional origin for routing, and a routing profile (vehicle settings JSON).

createTrip requires at least two stops. If you omit origin, routing uses stops[0] as the origin. For a simple A→B route, include both endpoints in stops: 

import {
  createTrip,
  createWaypoint,
  MEDIUM_DUTY_STRAIGHT_JSON,
} from "@trimblemaps/navigation-react-native";

const profile = {
  name: "Medium Duty Straight",
  json: MEDIUM_DUTY_STRAIGHT_JSON,
};

const origin = createWaypoint(40.203254, -74.796765, "Origin");
const destination = createWaypoint(40.214378, -74.792828, "Destination");

const trip = createTrip(
  [origin, destination],
  "Basic route",
  origin,
  profile,
);

Waypoints use latitude, longitude order (not GeoJSON). The third argument is the origin used for route calculation (defaults to stops[0]). The fourth argument is the routing profile. See Routing profiles.

Multi-stop example

When you have more than two stops, list every stop in order. You can set origin separately when routing should start from a point that is not the first listed stop (for example the device location): 

const trip = createTrip(
  [
    createWaypoint(40.214378, -74.792828, "Destination"),
    createWaypoint(40.220145, -74.788901, "Second stop"),
  ],
  "Delivery route",
  createWaypoint(40.203254, -74.796765, "Current location"),
  profile,
);

Mount NavigationView 

import { useEffect, useRef } from "react";
import {
  NavigationView,
  type NavigationViewRef,
} from "@trimblemaps/navigation-react-native";

export function NavigationScreen() {
  const navigationRef = useRef<NavigationViewRef>(null);

  return (
    <NavigationView
      ref={navigationRef}
      style={{ flex: 1 }}
      shouldSimulateRoute
      enableVanishingRouteLine
      initialCamera={{
        latitude: 40.203254,
        longitude: -74.796765,
        zoom: 14,
      }}
      onNavigationReady={() => {
        navigationRef.current
          ?.startNavigation(trip, {
            shouldSimulateRoute: true,
            enableVanishingRouteLine: true,
          })
          .catch((error) => console.error(error));
      }}
    />
  );
}

Call startNavigation from onNavigationReady (or after you confirm AccountManager.isLicensedForNavigation()). Use a ref typed as NavigationViewRef to access imperative methods.

ETA display

Arrival time labels may use destination-local or device-local time depending on platform and emulator settings. Treat ETA as approximate during development if simulators use different time zones.

Method Description
startNavigation(trip, options?) Fetch route and begin guidance
stopNavigation() End the session
pauseNavigation() / resumeNavigation() Pause or resume guidance
recenter() Recenter the map on the user
onBackPressed() Handle Android back during navigation
updateTripAndReroute(trip) Replace trip (for example after a profile change)
showAlternateRoutes(show) Toggle alternate route display
updateLocationRenderMode(mode) "normal", "gps", or "compass"

Common props

Prop Description
shouldSimulateRoute Simulate movement along the route (testing)
enableVanishingRouteLine Trim the route line behind the vehicle
tripPreviewEnabled Show trip preview UI before guidance
showAlternateRoutes Show alternate routes when available
locationRenderMode Location puck behavior

Android back button

Forward hardware back presses to the navigation view: 

import { BackHandler, Platform } from "react-native";

useEffect(() => {
  if (Platform.OS !== "android") {
    return;
  }
  const subscription = BackHandler.addEventListener("hardwareBackPress", () => {
    navigationRef.current?.onBackPressed();
    return true;
  });
  return () => subscription.remove();
}, []);

Events

NavigationView exposes many callbacks (onRouteProgressChange, onBannerInstruction, and others). See Navigation events.

Last updated November 5, 2026.
Contents