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

    Class POIsModule

    POIs Module for controlling Points of Interest displayed in the map style.

    This module manages the built-in POI layer from the vector map, allowing you to show/hide POIs and filter them by category. POIs are already part of the map style and include businesses, landmarks, and other points of interest.

    What this module owns: whether the style's POIs are shown, which categories, and any custom icon a category is drawn with. Their size, label colours and zoom thresholds are pois.* knobs on StylingModule. The knob pois.microMarkers hides the micro markers within the POIs this module shows, and never shows them while this module hides the POIs. 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 = [
      { 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 getShown isVisible resetConfig setVisible updateConfig waitUntilModuleReady get

    • Gets the events interface for handling 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
      • iconID: Icon sprite ID
      • 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>

      Gets the source and layer identifiers for all sources managed by this module.

      This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.

      The returned IDs are useful when you need 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
      const map = myModule.mapLibreMap;
      ids.mySource.layerIDs.forEach(layerId => {
        map.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    • Applies a configuration to this module.

      This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.

      Parameters

      • config: POIsModuleConfig | undefined

        The configuration object to apply to the module. Pass undefined to reset the configuration to default values.

      Returns void

      When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.

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

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

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

    • Retrieves a copy of the current module configuration.

      This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

      Returns NonNullable<POIsModuleConfig> | undefined

      A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.

      The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, opacity: 0.8 }

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

    • Returns features currently visible in the viewport.

      Returns { pois: POIsModuleFeature[] }

      An object containing visible POI features with properly typed properties.

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

    • Whether the POIs are set to be shown.

      Returns boolean

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

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

    • Resets the configuration of this module to its default values.

      This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

      Returns void

      After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // 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 nested object that was there — and the result is applied with applyConfig. This is the same on every module, whatever its applyConfig does with a whole configuration.

      Parameters

      • partial: Partial<NonNullable<CFG>>

        The properties to change.

      Returns void

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

      applyConfig to apply a whole configuration

    • Retrieves a POIsModule instance for the given map.

      Parameters

      • map: TomTomMap

        The TomTomMap instance to attach this module to.

      • Optionalconfig: POIsModuleConfig

        Optional initial configuration for visibility and filters.

      Returns Promise<POIsModule>

      A promise that resolves to the initialized POIsModule.

      Configuration:

      • visible: Initial visibility state
      • filters.categories: Category filter to apply on initialization

      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