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

POIs module

The POIs Module controls Points of Interest displayed on the map, allowing you to show/hide POIs, filter them by category, and draw a category with icons of your own.

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. See Who owns what.

Initialization

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

// Initialize map
const map = new TomTomMap({ mapLibre: { container: 'map' } });

// Get POIs module
const poisModule = await POIsModule.get(map);

Visibility control

Control POI layer visibility on the map:

// Initialize with hidden POIs
const poisModule = await POIsModule.get(map, {
    visible: false
});

// Hide all POIs
poisModule.setVisible(false);

// Show all POIs
poisModule.setVisible(true);

// Read the setting back: true
const visible = poisModule.isVisible();

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

Filter POIs by individual categories or category groups:

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

// Show categories
poisModule.updateConfig({
    filters: { categories: { show: 'only', values: ['RESTAURANT', 'CAFE_PUB', 'HOTEL_OR_MOTEL'] } }
});

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

// Show category groups
poisModule.updateConfig({
    filters: { categories: { show: 'only', values: ['FOOD_DRINKS_GROUP', 'SHOPPING_GROUP'] } }
});

// Hide category groups
poisModule.updateConfig({
    filters: { categories: { show: 'all-except', values: ['PARKING_GROUP', 'GAS_STATIONS_GROUP'] } }
});

// Reset filter and show all categories
poisModule.updateConfig({ filters: undefined });

show takes one of filterShowModes ('only', 'all-except'), exported from @tomtom-org/maps-sdk/map for building a mode picker or a schema.

Available category groups

The module supports predefined category groups for convenient filtering:

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:

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:

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

Handle user interactions with POIs:

// Click events
poisModule.events.on('click', (feature, lngLat) => {
    console.log('POI name:', feature.properties.name);
    console.log('Category:', feature.properties.category);
    console.log('ID:', feature.properties.id);
    console.log('Click coordinates:', lngLat);
});

// Hover events
poisModule.events.on('hover', (feature, lngLat) => {
    console.log('Hovering over:', feature.properties.name);
});

// Context menu (right-click)
poisModule.events.on('contextmenu', (feature, lngLat) => {
    console.log('Right-clicked POI:', feature.properties.name);
});

// Long hover
poisModule.events.on('long-hover', (feature, lngLat) => {
    console.log('Long hover on:', feature.properties.name);
});

// Remove event listeners
poisModule.events.off('click', handler);

POI feature properties

POI features include the following properties in events:

Querying visible features

Use getShown() to retrieve all POI features currently rendered in the visible map area:

const shown = poisModule.getShown();
console.log(`Visible POIs: ${shown.pois.length}`);
shown.pois.forEach(poi => {
    console.log(poi.properties.name, poi.properties.category);
});

API reference

For complete documentation of all POIs Module properties, methods, and types, see the POIsModule API Reference.

Related guides and examples

Services integration

Related examples

Related map modules