TomTom Maps SDK for JavaScript
This is the documentation of version 0.62.3. 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, and any custom icon a category is drawn with. How POIs look — icon size, the zoom they appear at, label colours, micro markers — is a Styling module knob (pois.*). pois.microMarkers can only hide micro markers within what this module shows, and pois.zoomShift composes with the category filters. 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', …] }

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:

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