Traffic incidents module

TrafficIncidentsModule controls the style's live traffic-incident layers: the affected stretch of road as a line coloured by delay, and a category icon per incident — accidents, closures, roadworks, weather — across the whole map.

What this module owns: whether the style's incident layers and icons are shown, which incidents, and how they look — visibility, filters, and the colour of each severity and the line width. Incidents you fetched yourself are drawn by the Traffic Incident Details Module instead. See Who owns what.

• Speed conditions on every road are the Traffic Flow Module's.
• The incidents along a route are its traffic sections.
• To draw exactly the incidents a trafficIncidentDetails call returned, use the Traffic Incident Details Module.

Initialization

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

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const trafficIncidentsModule = await TrafficIncidentsModule.get(map);

• get() adds the trafficIncidents style part when the style lacks it, reloading the style; on a custom style without incidents it throws.
• It is style-owned: every get() on one map returns the same instance.

Visibility

Incidents are hidden until shown. isVisible() reads the visible setting back, false while unset.

const trafficIncidentsModule = await TrafficIncidentsModule.get(map, { visible: true });

trafficIncidentsModule.setVisible(false);
trafficIncidentsModule.isVisible(); // false

Icon visibility

The icons show or hide apart from the lines, and always show the same incidents: the filters narrow both.

• icons.visible, which setIconsVisible sets, overrides visible for the icons. isIconsVisible() reads it back and, while it is unset, returns isVisible().
• setVisible clears icons.visible, so the icons follow visible again. Icons alone are { visible: false, icons: { visible: true } }, or setVisible(false) and then setIconsVisible(true) — in the other order the icons hide again.

// Lines without icons
const trafficIncidentsModule = await TrafficIncidentsModule.get(map, { visible: true, icons: { visible: false } });
trafficIncidentsModule.isIconsVisible(); // false

// Icons alone
trafficIncidentsModule.setVisible(false);
trafficIncidentsModule.setIconsVisible(true);
trafficIncidentsModule.isIconsVisible(); // true

// setVisible clears icons.visible: the icons follow visible again
trafficIncidentsModule.setVisible(true);
trafficIncidentsModule.getConfig(); // { visible: true }

isIconsVisible() reports the setting. Whether a style layer itself is shown is map.mapLibreMap.getLayoutProperty(layerId, 'visibility').

Filtering

filters narrows which incidents show, lines and icons alike, at get() or later through updateConfig. It works as the flow filters do: the fields are one filter, every field set must match, and each entry of its any list is an alternative.

Incident category

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

// Every incident but the weather
trafficIncidentsModule.updateConfig({
    filters: { incidentCategories: { show: 'all-except', values: ['rain', 'fog', 'frost', 'wind', 'flooding'] } },
});

The values are the incident categories of fullTrafficIncidentCategories, the tile-only animals-on-road and narrow-lanes included.

Severity

The playground below filters by delay magnitude from checkboxes:

trafficIncidentsModule.updateConfig({
    filters: { magnitudes: { show: 'only', values: ['major', 'moderate'] } },
});

The values are the delay magnitudes: unknown, minor, moderate, major and indefinite.

Delay duration

// At least 5 minutes of delay; incidents reporting no delay drop out too
trafficIncidentsModule.updateConfig({
    filters: { delays: { mustHaveDelay: true, minDelayMinutes: 5 } },
});

• mustHaveDelay drops the incidents that report no delay.
• minDelayMinutes drops those delaying traffic by less; without mustHaveDelay, the incidents reporting no delay stay.

Road category

roadCategories and roadSubCategories take the road categories and subcategories of the flow filters:

trafficIncidentsModule.updateConfig({
    filters: { roadCategories: { show: 'only', values: ['motorway', 'trunk'] } },
});

Multiple filters

// Major accidents, or a road closure of any magnitude
trafficIncidentsModule.updateConfig({
    filters: {
        incidentCategories: { show: 'only', values: ['accident'] },
        magnitudes: { show: 'only', values: ['major'] },
        any: [{ incidentCategories: { show: 'only', values: ['road-closed'] } }],
    },
});

Reset filters

trafficIncidentsModule.updateConfig({ filters: undefined });

Appearance

colors recolours the incident lines per delay severity, and widthFactor (0.5 to 2) multiplies their width.

• Each restyles the style's own incident layers, and reads the style's value while unset.
• A severity's outline follows its colour.
• The severities are minor, moderate, major, and closed, the outline of closed roads.

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

const trafficIncidentsModule = await TrafficIncidentsModule.get(map, {
    visible: true,
    colors: { major: '#b91c1c', closed: '#111827' },
    widthFactor: 1.5,
});
setKnob(trafficIncidentsModule, trafficIncidentsKnobCatalogue, 'colors.minor', '#facc15');

• The traffic sections of a route and the incidents you fetch yourself borrow these colours.
• getStyleColor reads them by their map-wide ids, such as traffic.incidents.colors.major, with or without the module, and so does the map effects plugin's bloom scope.

Events

events.on takes click, hover, long-hover and the other user events; the handler receives the incident as a TrafficIncidentsModuleFeature.

const unsubscribe = trafficIncidentsModule.events.on('click', (incident, lngLat) => {
    const { id, category, magnitudeOfDelay, delayInSeconds, description } = incident.properties;
});

• on returns the function that removes the handler; events.off('click') removes every click handler of the module (Cleanup).
• A tile feature carries the properties both incident sources share, plus tile fields such as description, roadCategory and averageSpeedKmph. Its id looks the full record up: trafficIncidentDetails({ ids: [id] }) (query by IDs).

Querying visible features

getRenderedFeatures() returns the incidents rendered in the current viewport, lines and icons:

const { trafficIncidents } = trafficIncidentsModule.getRenderedFeatures();
const accidents = trafficIncidents.filter((incident) => incident.properties.category === 'accident');

Every setting as data

trafficIncidentsKnobCatalogue lists the module's plain-valued settings with their kind, range or options and, where one value holds everywhere, their default, readable with no map loaded:

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

// [{ id: 'visible', kind: 'toggle', description: '…', default: false },
//  { id: 'icons.visible', kind: 'toggle', description: '…' }, …,
//  { id: 'filters.magnitudes.values', kind: 'enums', description: '…', options: ['unknown', 'minor', 'moderate', 'major', 'indefinite'] }, …]

• The filters knobs set the fields of the filter; the any list of filters is config only. Each show knob goes with its values knob, and unset, nothing is filtered.
• trafficIncidentsKnobIds lists the ids, TrafficIncidentsKnobId is their union, and TrafficIncidentsKnobValueOf<ID> the plain value one takes. The entry shape and its kinds are the modules guide's.
• Not in it: events.
• The traffic config playground builds its flow and incidents controls from the two catalogues and sets each with setKnob.

API reference

TrafficIncidentsModule, TrafficIncidentsModuleConfig and TrafficIncidentsModuleFeature.

Related guides and examples

Related guides

• Traffic overview - Every way the SDK draws traffic
• Traffic flow module - Live speed conditions on every road
• Traffic incident details module - The incidents you fetched, with focus
• Core traffic types - The categories and magnitudes the filters take

Related examples

• Traffic incidents - Live incidents, shown as the map loads
• Traffic incidents playground - Incidents filtered by severity, with a popup per incident
• Traffic config playground - Flow and incident presets, with every setting from the knob catalogues
• Map styling playground - The incident colour and width knobs, next to every other look knob of the map