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

POIs module

The POIs module controls the points of interest the map style draws. To draw search results or your own points, use the Places module.

What this module owns: whether the style's POI layers are shown, which categories, how they look — icon size, the zoom they appear at, label colours, micro markers (Appearance) — and any custom icon a category is drawn with. Who owns what compares every module.

Initialization

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

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

The POIs belong to the style, so POIsModule.get returns the one instance a map has: settings applied through one handle show through every other.

Visibility control

const poisModule = await POIsModule.get(map, { visible: false });

poisModule.setVisible(true);
poisModule.isVisible(); // true

isVisible() returns the visible setting. Until something sets it, it reports whether the style draws any POI layer.

Every setting as data

poisKnobCatalogue lists the settings of the module's configuration that a single control can hold, with their kind, a description and, where one holds, their default, readable with no map loaded:

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

const visible = poisKnobCatalogue.find(({ id }) => id === 'visible');
// { id: 'visible', kind: 'toggle', description: 'The POIs the map style draws.', default: true }
const values = poisKnobCatalogue.find(({ id }) => id === 'filters.categories.values');
// { id: 'filters.categories.values', kind: 'enums', description: '…', options: ['FOOD_DRINKS_GROUP', …, 'RESTAURANT', …] }
Id Kind Default
visible toggle true
filters.categories.show enum: only, all-except none
filters.categories.values enums: the category groups, then every category none
sizeFactor factor 0.5–1.5 1
minZoom number 3–18 none: the style's own, 6 on TomTom styles
zoomShift number −3–3 0
label.color, label.haloColor colour none: the style's own
microMarkers.visible toggle none: as the style ships them

Filtering

filters.categories shows only the categories and category groups it lists, or all-except them:

const poisModule = await POIsModule.get(map, {
    filters: { categories: { show: 'only', values: ['RESTAURANT', 'CAFE_PUB'] } },
});

poisModule.updateConfig({
    filters: { categories: { show: 'all-except', values: ['PARKING_GROUP', 'OPEN_CAR_PARKING_AREA'] } },
});

// Every category again
poisModule.updateConfig({ filters: undefined });

Available category groups

Appearance

The size of the POIs, the zoom they appear at, their label colours and the micro markers restyle the style's own POI layers, each reading the style's own value while unset:

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

const poisModule = await POIsModule.get(map, {
    sizeFactor: 1.2,
    minZoom: 12,
    label: { color: '#334155', haloColor: '#ffffff' },
    microMarkers: { visible: false },
});
setKnob(poisModule, poisKnobCatalogue, 'zoomShift', 1); // later and sparser

Custom icons per category

icon.categoryIcons draws the POIs of a category with an image of your own, while every other category keeps the style's icon. It takes the entries a Places module takes, so one list restyles the map's POIs and the places you show alike:

import { PlacesModule, POIsModule } from '@tomtom-org/maps-sdk/map';

const categoryIcons = [
    { id: 'RESTAURANT', image: restaurantSvg },
    { id: 'HOTEL_OR_MOTEL', image: '/icons/hotel-pin.png', offsetY: -17 },
];

const poisModule = await POIsModule.get(map, { icon: { categoryIcons } });
const searchResults = await PlacesModule.create(map, { markerType: 'base-map', icon: { categoryIcons } });

// The style's own icons again
poisModule.updateConfig({ icon: undefined });

Events

click, contextmenu, hover and long-hover hand over the POI under the pointer (event types):

import { getPlaceDetails } from '@tomtom-org/maps-sdk/services';

const stopListening = poisModule.events.on('click', async (feature, lngLat) => {
    console.log(feature.properties.name, feature.properties.category, lngLat);
    // The POI id is a place id: fetch its opening hours, phone and more
    const place = await getPlaceDetails({ entityId: feature.properties.id });
});
poisModule.events.on('hover', (feature) => console.log(feature.properties.name));

stopListening(); // removes this handler alone
poisModule.events.off('hover'); // removes every hover handler

POI feature properties

A POI feature (POIsModuleFeature) carries the style's own values:

Querying visible features

getRenderedFeatures() returns the POI features rendered in the viewport:

const { pois } = poisModule.getRenderedFeatures();
pois.forEach((poi) => console.log(poi.properties.name, poi.properties.category));

API reference

POIsModule lists every method, and POIsModuleConfig every setting.

Related guides and examples

Services integration

Related examples

Related map modules