TomTom Maps for JavaScript
    Preparing search index...

    Class PlacesModule

    Map module for displaying and managing place markers.

    The PlacesModule provides functionality to display location markers (pins) on the map for points of interest, search results, or custom locations. It supports various marker styles, custom icons, text labels, and interactive events.

    Features:

    • Multiple marker styles (pin, circle, POI-like)
    • Custom icons per POI category
    • Text labels with styling options
    • Data-driven styling via MapLibre expressions
    • Interactive events (click, hover, etc.)
    • Support for custom feature properties
    • EV charging station availability display (opt-in)

    Marker Styles:

    • pin: Traditional teardrop-shaped map pins
    • circle: Simple circular markers
    • base-map: Mimics built-in POI layer styling

    EV Charging Station Availability: When displaying EV charging stations with availability data from getPlacesWithEVAvailability, the module can:

    • Show available/total charging points (e.g., "3/10")
    • Color-code availability (green = good, orange = limited, red = none/low)
    • Display as formatted text within the station's label

    This feature is disabled by default. To enable it, set evAvailability.enabled to true in the configuration.

    Common Use Cases:

    • Search result visualization
    • Custom location markers
    • Store locators
    • EV charging station maps with real-time availability
    • Delivery/pickup points
    • Saved locations display
    // Create places module with pin markers
    const placesModule = await PlacesModule.get(map, {
      icon: {
        categoryIcons: []
      },
      text: {
        field: (place) => place.properties.poi?.name || 'Unknown'
      },
      theme: 'pin'
    });

    // Display places from search
    await placesModule.show(searchResults);

    // EV Charging Stations - Opt-in to availability display
    const evStations = await PlacesModule.get(map, {
      evAvailability: { enabled: true }
    });
    const results = await search({ poiCategories: ['ELECTRIC_VEHICLE_STATION'] });
    evStations.show(await getPlacesWithEVAvailability(results)); // Shows availability

    // Granular control: Enable for searched stations only, background stations without
    const bgStations = await PlacesModule.get(map); // EV availability disabled
    const searched = await PlacesModule.get(map, {
      evAvailability: { enabled: true }
    });

    // Handle clicks
    placesModule.events.on('click', (feature) => {
      console.log('Clicked:', feature.properties);
    });

    placesModule.events.on('hover', (feature) => {
      showTooltip(feature.properties.poi?.name);
    });

    Places Guide

    Hierarchy (View Summary)

    Index

    Accessors

    events sourceAndLayerIDs

    Methods

    applyConfig applyExtraFeatureProps applyIconConfig applyTextConfig applyTheme cleanEventState cleanEventStates clear getConfig putEventState resetConfig show waitUntilModuleReady get

    Accessors

    • 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');
      });

    Methods

    • 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: PlacesModuleConfig | 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.

      // 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

    • Applies additional feature properties to displayed places.

      Parameters

      • extraFeatureProps: { [key: string]: any }

        Object mapping property names to values or functions.

      Returns void

      Useful for adding computed properties or metadata for styling/filtering.

      placesModule.applyExtraFeatureProps({
        category: (place) => place.properties.poi?.categories?.[0],
        rating: (place) => place.properties.poi?.rating || 0,
        isOpen: true
      });

    • Updates the icon configuration for displayed places.

      Parameters

      Returns void

      • Changes apply immediately to currently shown places
      • Custom icons are loaded if not already in style
      • Other configuration properties remain unchanged
      placesModule.applyIconConfig({
        categoryIcons: [
          { category: 'RESTAURANT', id: 'restaurant-icon', image: '/icons/food.png' }
        ]
      });

    • Updates the text/label configuration for displayed places.

      Parameters

      Returns void

      Supports both functions and MapLibre expressions for dynamic text.

      // Use function
      placesModule.applyTextConfig({
        field: (place) => place.properties.poi?.name || 'Unknown'
      });

      // Use MapLibre expression
      placesModule.applyTextConfig({
        field: ['get', 'title'],
        size: 14,
        color: '#333'
      });

    • Updates the visual theme for displayed places.

      Parameters

      • theme: PlacesTheme

        The theme style to apply to place markers.

      Returns void

      Available Themes:

      • pin: Traditional teardrop-shaped map pins
      • circle: Simple circular markers
      • base-map: Mimics the map's built-in POI layer style with category icons

      Changes apply immediately to all currently shown places. Other configuration properties (icon config, text config) remain unchanged.

      // Switch to pin markers
      placesModule.applyTheme('pin');

      // Use simple circles
      placesModule.applyTheme('circle');

      // Match map's POI style (ideal to blend in)
      placesModule.applyTheme('base-map');

    • Removes an event state from a specific place.

      Parameters

      Returns void

      placesModule.cleanEventState({ index: 0 });

    • Removes event states from multiple places.

      Parameters

      Returns void

      // Remove all event states
      placesModule.cleanEventStates();

      // Remove only hover states
      placesModule.cleanEventStates({ states: ['hover'] });

    • Removes all places from the map.

      Returns Promise<void>

      • Clears all displayed places
      • Does not reset styling configuration
      • Module remains initialized and ready for new data
      await placesModule.clear();

    • 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<PlacesModuleConfig> | 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

    • Programmatically sets an event state on a specific place.

      Parameters

      Returns void

      Use this to make places appear clicked or hovered programmatically.

      // Make first place appear clicked
      placesModule.putEventState({
        index: 0,
        state: 'click',
        mode: 'put'
      });

    • 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

    • Displays the given places on the map.

      Parameters

      • places: Place | Places | Place[]

        Place data to display. Can be a single Place, array of Places, or a Places FeatureCollection.

      Returns Promise<void>

      Behavior:

      • Replaces any previously shown places
      • Applies current module styling configuration
      • Automatically generates labels if text config is set
      • Waits for module to be ready before displaying

      Data Sources:

      • TomTom Search API results
      • Custom place objects matching the Place interface
      • GeoJSON Point features

      Display search results:

      import { search } from '@tomtom-international/maps-sdk-js/services';

      const results = await search({ query: 'coffee' });
      await placesModule.show(results);

      Display single place:

      await placesModule.show({
        type: 'Feature',
        geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
        properties: {
          address: { freeformAddress: 'Amsterdam' },
          poi: { name: 'Amsterdam Central' }
        }
      });

      Display multiple places:

      await placesModule.show([place1, place2, place3]);

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods