TomTom Maps for JavaScript
    Preparing search index...

    Class RoutingModule

    Map module for displaying and managing route visualizations.

    The RoutingModule provides comprehensive functionality for displaying routes on the map, including route lines, alternative routes, turn-by-turn guidance, and interactive waypoints. It integrates seamlessly with the TomTom Routing API.

    Features:

    • Display route lines with customizable styling
    • Show alternative routes with different styling
    • Interactive waypoint markers (drag, add, remove)
    • Turn-by-turn guidance instructions
    • Route section highlighting
    • Distance and duration information
    • Support for multiple routes simultaneously

    Common Use Cases:

    • Turn-by-turn navigation displays
    • Route planning and comparison
    • Multi-stop route optimization
    • Interactive route editing
    • Fleet management route visualization
    // Create the module
    const routingModule = await RoutingModule.getInstance(map, {
      displayUnits: {
        distance: { type: 'metric' }
      }
    });

    // Calculate and display a route
    const result = await calculateRoute({
      key: 'your-api-key',
      locations: [
        [4.9041, 52.3676],  // Amsterdam
        [4.4777, 51.9244]   // Rotterdam
      ],
      routeOptions: {
        travelMode: 'car',
        routeType: 'fastest'
      }
    });

    await routingModule.showRoutes(result);

    Routing Guide

    Hierarchy (View Summary)

    Index

    Accessors

    events sourceAndLayerIDs

    Methods

    applyConfig clearRoutes clearWaypoints getConfig getLayerToRenderLinesUnder getShown resetConfig selectRoute showRoutes showWaypoints waitUntilModuleReady get

    Accessors

    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      Gets the source and layer identifiers for all sources managed by this module.

      This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.

      The returned IDs are useful when you need to:

      • Directly manipulate layers using MapLibre's native API
      • Identify which layers on the map belong to this module
      • Set layer ordering or positioning relative to other layers
      • Access source or layer properties through MapLibre methods
      const ids = myModule.sourceAndLayerIDs;
      console.log(ids);
      // {
      //   mySource: {
      //     sourceID: 'my-source-id',
      //     layerIDs: ['layer-1', 'layer-2']
      //   }
      // }

      // Use with MapLibre API
      const map = myModule.mapLibreMap;
      ids.mySource.layerIDs.forEach(layerId => {
        map.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    Methods

    • Applies a configuration to this module.

      This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.

      Parameters

      • config: RoutingModuleConfig | undefined

        The configuration object to apply to the module. Pass undefined to reset the configuration to default values.

      Returns void

      When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Clears any previously shown routes from the map.

      Returns Promise<void>

      • Clears all route-related layers (lines, sections, guidance, summaries)
      • Does NOT clear waypoints (use clearWaypoints)
      • Module remains initialized and ready for new routes
      await routing.clearRoutes();

    • Clears any previously shown waypoints from the map. If nothing was shown before, nothing happens.

      Returns Promise<void>

    • Retrieves a copy of the current module configuration.

      This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

      Returns NonNullable<RoutingModuleConfig> | undefined

      A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.

      The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, opacity: 0.8 }

      // When no config is applied
      myModule.resetConfig();
      console.log(myModule.getConfig()); // undefined

    • Returns the map style layer under which route lines are rendered.

      • Useful if you want to render extra layers just above the route ones but not on top of everything else.
      • It might differ depending on the loaded style/version.

      Returns string

    • Returns the currently shown routes and waypoints.

      Returns {
          chargingStops: Waypoints;
          ferries: RouteSections;
          incidents: RouteSections<DisplayTrafficSectionProps>;
          instructionArrows: DisplayInstructionArrows;
          instructionLines: DisplayInstructions;
          mainLines: Routes<DisplayRouteProps>;
          summaryBubbles: DisplayRouteSummaries;
          tollRoads: RouteSections;
          tunnels: RouteSections;
          vehicleRestricted: RouteSections;
          waypoints: Waypoints<WaypointDisplayProps>;
      }

      An object containing all currently displayed routing data.

      Returns the exact data that was passed to the showRoutes() and showWaypoints() methods.

      Returned Data:

      • mainLines: Main route lines (selected and alternative)
      • waypoints: Route waypoints (start, stops, finish)
      • incidents: Traffic incidents on routes
      • ferries: Ferry sections
      • chargingStops: EV charging stations
      • tollRoads: Toll road sections
      • tunnels: Tunnel sections
      • vehicleRestricted: Vehicle-restricted sections
      • instructionLines: Turn-by-turn instruction lines
      • instructionArrows: Instruction arrow markers
      • summaryBubbles: Route summary popups
      const shown = routingModule.getShown();
      console.log(`Showing ${shown.mainLines.features.length} routes`);
      console.log(`Showing ${shown.waypoints.features.length} waypoints`);
      console.log(`Showing ${shown.chargingStops.features.length} charging stops`);

      Check if any routes are displayed:

      const shown = routingModule.getShown();
      if (shown.mainLines.features.length > 0) {
        console.log('Routes are displayed');
      } else {
        console.log('No routes displayed');
      }

    • Resets the configuration of this module to its default values.

      This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

      Returns void

      After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

    • Changes which route appears as selected.

      Parameters

      • index: number

        Zero-based index of the route to select.

      Returns Promise<void>

      Visual Changes:

      • Selected route appears more prominent (thicker, brighter)
      • Previously selected route becomes deselected style
      • Updates all route-related features (sections, guidance)

      Requirements:

      • Route must already be displayed via showRoutes
      • Index must be within range of displayed routes
      // Show multiple routes
      await routingModule.showRoutes(routes);

      // User clicks alternative route
      await routingModule.selectRoute(1);

      // Switch back to first route
      await routingModule.selectRoute(0);

    • Displays the given routes on the map.

      Parameters

      • routes: Route | Routes

        Route data from Routing API or custom routes.

      • Optionaloptions: ShowRoutesOptions

        Optional configuration for route selection and display.

        • selectedIndex

          Index of the route to display as selected (default: 0).

      Returns Promise<void>

      Waypoints are NOT shown by this method. Route lines are drawn but start/stop/destination markers are not. To display waypoint markers, call showWaypoints separately. Alternatively, use PlacesModule to display waypoints as fully customizable place markers.

      Behavior:

      • Replaces any previously shown routes
      • Shows all route-related features: lines, sections, summaries, guidance
      • First route is selected by default (appears more prominent)

      Route Features:

      • Main route lines (selected and deselected styles)
      • Traffic sections with delays
      • Ferry, tunnel, and toll sections
      • EV charging stations (for EV routes)
      • Turn-by-turn instruction lines and arrows
      • Summary bubbles with distance/time/traffic info

      Show a route (no waypoint markers):

      await routing.showRoutes(response.routes);
      // Waypoint markers are NOT shown — call showWaypoints() to add them

      Show routes and waypoint markers:

      const locations = [[4.9, 52.4], [4.5, 51.9]];
      const response = await calculateRoute({ locations });
      await routing.showRoutes(response.routes);
      await routing.showWaypoints(locations); // Show start/destination markers separately

      Show multiple routes with specific selection:

      await routing.showRoutes(response.routes, { selectedIndex: 1 });

    • Displays waypoint markers (start, stop, and destination pins) on the map.

      Parameters

      Returns Promise<void>

      Waypoint markers are not shown by showRoutes — this method must be called separately to display them. For more control over marker appearance and behavior, consider using PlacesModule to render waypoints as place markers instead.

      Show routes and then waypoints:

      const locations = [[4.9041, 52.3676], [4.4777, 51.9244]];
      const response = await calculateRoute({ locations });
      await routingModule.showRoutes(response.routes);
      await routingModule.showWaypoints(locations); // Must be called separately

    • Make sure the map is ready before create an instance of the module and any other interaction with the map

      Parameters

      Returns Promise<RoutingModule>

      Returns a promise with a new instance of this module

      Configuration Options:

      • displayUnits: Distance units (metric/imperial)
      • waypointsSource: Waypoint entry point options
      • layers: Complete layer styling configuration

      Default Styling: If no custom layers are provided, uses defaultRoutingLayers.

      Default initialization:

      const routingModule = await RoutingModule.get(map);

      With custom configuration:

      const routingModule = await RoutingModule.get(map, {
        displayUnits: 'imperial',
        waypointsSource: {
          entryPoints: 'main-when-available'
        }
      });

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods