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

    Class POIsModule

    A module that controls the points of interest the map style displays.

    It manages the built-in POI layer of the vector map, so you can show or hide POIs and filter them by category. POIs are already part of the map style and include businesses, landmarks and other points of interest.

    This module owns whether the style's POIs are shown, which categories, any custom icon a category is drawn with, and their look (size, label colours and zoom thresholds). The micro markers show or hide on their own (microMarkers.visible), never while the POIs are hidden. See Who owns what. poisKnobCatalogue lists the settings of its configuration a knob holds.

    Features:

    • Toggle POI visibility on/off
    • Filter by POI categories or category groups
    • Custom icons per POI category (POIIconConfig)
    • Event handling for POI interactions
    • Based on vector tile data in the map style

    POI categories:

    • Individual categories (e.g., RESTAURANT, HOTEL_OR_MOTEL, PARKING_GARAGE)
    • Category groups (e.g., FOOD_DRINKS_GROUP, SHOPPING_GROUP, TRANSPORTATION_GROUP)

    Difference from PlacesModule:

    • POIsModule: Controls existing POIs in the map style
    • PlacesModule: Displays custom place data from Search API or other sources

    Basic usage:

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

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

    // Toggle visibility
    poisModule.setVisible(false);
    poisModule.setVisible(true);

    Filter specific categories:

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

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

    // Show every POI again
    poisModule.updateConfig({ filters: undefined });

    Filter using category groups:

    // Show only food and shopping POIs
    poisModule.updateConfig({
      filters: { categories: { show: 'only', values: ['FOOD_DRINKS_GROUP', 'SHOPPING_GROUP'] } },
    });

    Custom icons per category, shared with the places a PlacesModule shows:

    const categoryIcons: CustomImage<MapStylePOICategory>[] = [
      { id: 'RESTAURANT', image: restaurantSvg },
      { id: 'HOTEL_OR_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 },
    ];
    poisModule.updateConfig({ icon: { categoryIcons } });
    searchResults.updateConfig({ icon: { categoryIcons } });

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

    Event handling:

    pois.events.on('click', (feature, lngLat) => {
      console.log('Clicked POI:', feature.properties.name);
      console.log('Category:', feature.properties.category);
    });

    POIs Guide

    Hierarchy (View Summary)

    Index
    events sourceAndLayerIDs
    applyConfig getConfig getRenderedFeatures isVisible resetConfig setVisible updateConfig get

    • The events of user interactions with POIs.

      Returns CombinedEvents<POIsModuleFeature, POIsModuleConfig, never>

      The module's events, with on / off for handlers and where for scoping.

      Supported events:

      • click: User clicks on a POI
      • contextmenu: User right-clicks on a POI
      • hover: Mouse enters a POI
      • long-hover: Mouse hovers over POI for extended time

      Event feature properties:

      • id: Unique POI identifier
      • name: POI name in native language
      • category: POI category
      • group: Category group
      • priority: Importance level (lower = more important)
      pois.events.on('click', (feature, lngLat) => {
        console.log('POI:', feature.properties.name);
        console.log('Category:', feature.properties.category);
        console.log('ID:', feature.properties.id);
      });

      pois.events.on('hover', (feature) => {
        showTooltip(feature.properties.name);
      });
    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      The MapLibre source and layer IDs of all sources this module creates and manages.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its MapLibre source ID and an array of the IDs of that source's layers.

      Use these IDs to:

      • Directly manipulate layers using MapLibre's native API
      • Identify which layers on the map belong to this module
      • Set layer ordering or positioning relative to other layers
      • Access source or layer properties through MapLibre methods
      const ids = myModule.sourceAndLayerIDs;
      console.log(ids);
      // {
      //   mySource: {
      //     sourceID: 'my-source-id',
      //     layerIDs: ['layer-1', 'layer-2']
      //   }
      // }

      // Use with MapLibre API
      ids.mySource.layerIDs.forEach(layerId => {
        map.mapLibreMap.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    • Applies a configuration to this module.

      The module updates its behaviour and appearance to match. It stores the configuration and reapplies it automatically when the map style changes.

      Parameters

      • config: POIsModuleConfig | undefined

        The configuration to apply. Pass undefined to reset it to the default values.

      Returns void

      The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.

      Use it for settings your code writes. It takes every setting, typed, including the ones no knob covers (layer specs, callbacks, MapLibre expressions), and checks no value at run time. For settings held as data, from a control, storage or a language model, use setKnobs.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Returns a shallow copy of the current module configuration, or undefined if none is applied.

      Returns NonNullable<POIsModuleConfig> | undefined

      A shallow copy of the current configuration, or undefined. It is a copy so that you can't modify the internal state by accident.

      Only the top-level properties are copied. Nested objects and arrays still reference the original configuration. This is enough for most use cases, but keep it in mind with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, color: '#E63312' }

      // When no config is applied
      myModule.resetConfig();
      console.log(myModule.getConfig()); // undefined

    • Returns the features the map renders in the viewport, from its vector tiles.

      Returns { pois: POIsModuleFeature[] }

      The visible POI features, with typed properties.

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

    • Whether the POIs are set to be shown.

      Returns boolean

      The visible setting, or, while nothing has set it, whether the style draws any POI layer.

      if (pois.isVisible()) {
        console.log('POIs are displayed');
      }

    • Resets this module's configuration to its default values.

      It clears any applied configuration and restores the module to its initial state, the same as calling applyConfig(undefined).

      Returns void

      The module then behaves as if no configuration was ever applied. Any custom settings, styling or behaviour changes are replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

    • Sets the visibility of POI layers.

      Parameters

      • visible: boolean

        true to show POIs, false to hide them.

      Returns void

      Changes are applied immediately if the map is ready.

      pois.setVisible(false); // Hide all POIs
      pois.setVisible(true);  // Show all POIs

    • Changes part of the configuration and keeps the rest.

      The given properties are laid over the current configuration one level deep, so a nested object you pass replaces the one that was there. The result is applied with applyConfig. This works the same on every module, whatever its applyConfig does with a whole configuration.

      Parameters

      • partial: Partial<NonNullable<CFG>>

        The properties to change.

      Returns void

      Use it for settings your code writes, as applyConfig: typed, and not checked at run time. To change nested values and keep the ones beside them, or to set values held as data, use setKnobs, which reaches each by its path and checks it.

      routing.applyConfig({ displayUnits: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
      routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial

      applyConfig to apply a whole configuration

    • Retrieves a POIsModule instance for the given map.

      Parameters

      Returns Promise<POIsModule>

      Error if the POI source is not found in the map style

      Default initialization:

      const poisModule = await POIsModule.get(map);

      With initial filter:

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

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods