TomTom Maps SDK for JavaScript

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.

The module owns whether the style's POI layers are shown, which categories and POIs show and how they look. The look covers icon size, the zoom POIs 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. A setting you apply through one handle shows through every other. A configuration passed to a later get replaces the one it holds, as applyConfig does.

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 module's settings that a single control can hold, with their kind, a description and their default, if any. You can read it 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; the micro markers keep their own
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 });

Filtering by id

filters.ids shows only the POIs it lists, or all-except them, by the id the module's events and getRenderedFeatures() give each POI. To hide a POI whose category you keep, list its id:

const hidden = [];
poisModule.events.on('click', (feature) => {
    hidden.push(feature.properties.id);
    const { filters } = poisModule.getConfig() ?? {};
    poisModule.updateConfig({ filters: { ...filters, ids: { show: 'all-except', values: hidden } } });
});

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 keeps the style's value until you set it:

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 your own image. Every other category keeps the style's icon. It takes the same entries as the Places module, so one list restyles the map's POIs and the places you show:

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