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

Places Module

The Places Module allows you to display and interact with places on your TomTom map. You can add search results, custom locations, and handle user interactions.

Initialization

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

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

// Initialize Places module with default configuration
const placesModule = await PlacesModule.get(map);

Displaying Places

Display one or multiple places on the map:

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

// Show single place
await placesModule.show({
  id: 'custom-place-1',
  type: 'Feature',
  geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
  properties: {
    type: 'POI',
    address: { freeformAddress: 'Custom Place 1, Amsterdam' },
    poi: { name: 'Custom Place' }
  }
});

// Show multiple places
await placesModule.show([place1, place2, place3]);

const searchResults = await search({
    query: 'restaurants',
    position: [4.9041, 52.3676], // Amsterdam
    limit: 10
});

// Show search results
await placesModule.show(searchResults);

// Remove all places from the map:
await placesModule.clear();

Custom Styling

Theme

Themes control the overall look of place markers. Choose one at initialization or swap at runtime:

// Initialize with a specific theme
const placesModule = await PlacesModule.get(map, { theme: 'base-map' });

// Or swap at runtime
placesModule.applyTheme('circle-icon');

// Micro-only rendering: combine `base-map` with a hidden `main` layer
const placesModule = await PlacesModule.get(map, {
    theme: 'base-map',
    layers: { main: { layout: { visibility: 'none' } } },
});

Text Styling

Customize labels for places using text configuration:

// Make POI names red and other places blue
const customTextConfig: PlaceTextConfig = {
    color: ['match', ['get', 'type'], 'POI', '#D32F2F', '#1976D2']
};

// Initialize with custom text styling
const placesModule = await PlacesModule.get(map, {
    text: customTextConfig,
});

// Or apply after initialization
placesModule.applyTextConfig(customTextConfig);

Icon Styling

Customize place icons and markers. Custom icons work under every theme: when a category is mapped, features in that category use the provided sprite; otherwise the theme's default icon (the base-map style's category/group expression or the default pin) still renders.

// Per-category custom images — layered on top of any theme
const customIconConfig: PlaceIconConfig = {
  categoryIcons: [
    { id: 'RESTAURANT', image: '/icons/food.png', pixelRatio: 2 },
    { id: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }
  ]
};

// Initialize with custom icon styling
const placesModule = await PlacesModule.get(map, {
  theme: 'pin',
  icon: customIconConfig
});

// Or apply after initialization
placesModule.applyIconConfig(customIconConfig);

Extra Properties

Add custom properties to places for advanced styling or filtering:

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

Events

User events

Handle user interactions with places:

// Click events
placesModule.events.on('click', (feature, lngLat) => {
    console.log('Click coordinates:', lngLat);
    console.log('Place title:', feature.properties.title);
    console.log('Place coordinates:', feature.geometry.coordinates);
});

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

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

Programmatic Event States

Manually control visual states of places:

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

// Remove event state from specific place
placesModule.cleanEventState({ index: 0 });

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

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

Multiple Module Instances

You can create multiple independent instances of the Places module, each with its own configuration and data. This is useful for displaying different sets of places with distinct styling or behavior.

// Create separate instances for different purposes
const restaurantPlaces = await PlacesModule.get(map, {
    theme: 'pin',
    icon: {
        categoryIcons: [{ id: 'RESTAURANT', image: '/icons/restaurant.png', pixelRatio: 2 }]
    }
});

const hotelPlaces = await PlacesModule.get(map, {
    theme: 'circle-icon',
    icon: {
        categoryIcons: [{ id: 'HOTEL_MOTEL', image: '/icons/hotel.png', pixelRatio: 2 }]
    }
});

// Each instance manages its own places independently
await restaurantPlaces.show(restaurantResults);
await hotelPlaces.show(hotelResults);

Reading Shown Data

Use getShown() to retrieve the places currently displayed on the map. This returns the exact data previously passed to show():

const shown = placesModule.getShown();
console.log(`Showing ${shown.places.features.length} places`);

API Reference

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

Related Guides and Examples

Services Integration

Related Examples

Related Map Modules