TomTom Maps SDK for JavaScript
This is the documentation of version 0.62.0. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Class TrafficIncidentsModule

    Traffic Incidents Module for displaying and configuring real-time traffic incidents on the map.

    This module controls the vector tile traffic incidents layers that show traffic events like accidents, road closures, construction, and hazards.

    What this module owns: whether the style's incident layers are shown, and which incidents. Each magnitude's colour and the line width are traffic.incidents.* knobs on StylingModule. See Who owns what.

    Features:

    • Toggle incidents visibility on/off
    • Separate visibility control for incident icons
    • Filter by incident type (accident, construction, etc.)
    • Filter by severity/delay magnitude
    • Filter by road categories
    • Icon and line/polygon visualization

    Incident Types:

    • Accidents
    • Road closures
    • Construction/road works
    • Weather conditions (fog, ice, rain, etc.)
    • Lane closures
    • Traffic jams
    • Broken down vehicles

    Basic usage:

    import { TrafficIncidentsModule } from '@tomtom-org/maps-sdk/map';

    // Get module (auto-add to style if needed)
    const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
      visible: true
    });

    // Toggle visibility
    trafficIncidentsModule.setVisible(false);
    trafficIncidentsModule.setVisible(true);

    // Control icons separately
    trafficIncidentsModule.setIconsVisible(false);

    Filter by incident type:

    // Show only accidents and road closures
    trafficIncidentsModule.updateConfig({
      filters: { any: [{ incidentCategories: { show: 'only', values: ['accident', 'road-closed'] } }] },
    });

    // Hide construction
    trafficIncidentsModule.updateConfig({
      filters: { any: [{ incidentCategories: { show: 'all-except', values: ['roadworks'] } }] },
    });

    Filter by severity:

    // Show only major delays
    incidents.updateConfig({ filters: { any: [{ magnitudes: { show: 'only', values: ['major'] } }] } });

    // Show incidents with at least 10 minutes delay
    incidents.updateConfig({ filters: { any: [{ delays: { mustHaveDelay: true, minDelayMinutes: 10 } }] } });

    // Show every incident again
    incidents.updateConfig({ filters: undefined });
    • Traffic Incidents Guide
    • Traffic Guide
    • TrafficIncidentDetailsModule — for rendering incidents fetched via the trafficIncidentDetails() REST service as a developer-controlled overlay (use the details module when you need typed incident objects in app code; this vector-tile module remains the recommended default for visual fidelity).

    Hierarchy (View Summary)

    Index
    events sourceAndLayerIDs
    applyConfig getConfig getShown isIconsVisible isVisible resetConfig setIconsVisible setVisible updateConfig waitUntilModuleReady get
    • 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');
      });

    • 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: TrafficIncidentsModuleConfig | 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.

      The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.

      // 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

    • 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<TrafficIncidentsModuleConfig> | 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 features currently visible in the viewport.

      Returns { trafficIncidents: TrafficIncidentsModuleFeature[] }

      An object containing visible traffic incident features.

      Returns all incident features currently rendered in the visible map area, including both incident areas/lines and icon markers.

      Feature Properties: Properties depend on the traffic incidents vector tile schema and may include:

      • Incident type/category
      • Severity/magnitude
      • Delay information
      • Road affected
      • Description
      const shown = incidents.getShown();
      console.log(`Visible incidents: ${shown.trafficIncidents.length}`);
      shown.trafficIncidents.forEach(incident => {
        console.log('Incident:', incident.properties);
      });

      Filter and analyze visible incidents:

      const shown = incidents.getShown();
      const accidents = shown.trafficIncidents.filter(
        incident => incident.properties.category === 'accident'
      );
      console.log(`Accidents in view: ${accidents.length}`);

    • Whether the incident icons are set to be shown.

      Returns boolean

      The icons.visible setting and, while it is unset, isVisible. It is true for the icons-only state, { visible: false, icons: { visible: true } }.

      incidents.setVisible(false);
      incidents.setIconsVisible(true);
      incidents.isIconsVisible(); // true: the icons show alone

    • Whether traffic incidents are set to be shown.

      Returns boolean

      The visible setting; false while nothing has set it, as traffic is hidden until shown. isIconsVisible reads the icons setting.

      if (incidents.isVisible()) {
        console.log('Incidents are 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

    • Sets the visibility of incident icon layers.

      Parameters

      • visible: boolean

        true to show icons, false to hide them.

      Returns void

      This controls only the icon/symbol layers, not the incident area polygons or lines. It stores icons.visible, which overrides visible for the icons until the next setVisible: setVisible(false) then setIconsVisible(true) shows the icons alone.

      // Hide icons but keep incident areas visible
      incidents.setIconsVisible(false);

      // Show icons
      incidents.setIconsVisible(true);

    • Sets the visibility of all traffic incident layers.

      Parameters

      • visible: boolean

        true to show incidents, false to hide them.

      Returns void

      This controls all incident layers including icons, lines, and polygons, and clears icons.visible, so the icons follow visible again.

      incidents.setVisible(false); // Hide all incidents
      incidents.setVisible(true);  // Show all incidents

    • Changes part of the configuration and keeps the rest.

      The given properties are laid over the current configuration — one level deep, so a nested object you pass replaces the nested object that was there — and the result is applied with applyConfig. This is the same on every module, whatever its applyConfig does with a whole configuration.

      Parameters

      • partial: Partial<NonNullable<CFG>>

        The properties to change.

      Returns void

      routing.applyConfig({ displayUnits: 'imperial', color: '#0a3653' });
      routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial

      applyConfig to apply a whole configuration

    • Retrieves a TrafficIncidentsModule instance for the given map.

      Parameters

      Returns Promise<TrafficIncidentsModule>

      A promise that resolves to the initialized TrafficIncidentsModule.

      Configuration:

      • visible: Initial visibility state for all incidents
      • icons.visible: Initial visibility for incident icons
      • ensureAddedToStyle: Auto-add traffic incidents to style if missing
      • filters: Incident type, severity, and delay filters, for lines and icons alike

      trafficIncidentsKnobCatalogue lists the plain-valued settings as data.

      Error if traffic incidents source is not in style and ensureAddedToStyle is false

      Default initialization:

      const trafficIncidentsModule = await TrafficIncidentsModule.get(map);

      With configuration:

      const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
        visible: true,
        icons: { visible: true },
        filters: {
          any: [{
            incidentCategories: {
              show: 'only',
              values: ['accident', 'road-closed', 'jam']
            }
          }]
        }
      });

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods