TomTom Maps for JavaScript
    Preparing search index...

    Class BaseMapModule

    Base Map Module for controlling standard map layers and their visibility.

    This module manages the fundamental map layers including background, water, land, roads, buildings, labels, and other vector tile layers from the base map style.

    Managed Layers:

    • Background and terrain
    • Water bodies and coastlines
    • Country and administrative borders
    • Buildings (2D and 3D)
    • Road lines, labels, and shields
    • Place labels at various zoom levels
    • House numbers

    Does NOT Include:

    Use Cases:

    • Toggle base map visibility on/off
    • Show only specific layer groups (e.g., roads only)
    • Create custom map appearances by hiding certain elements
    • Build overlay maps with selective base layers

    Basic usage:

    // Get module with default configuration
    const baseMap = await BaseMapModule.get(map);

    // Toggle visibility
    baseMap.setVisible(false); // Hide all base layers
    baseMap.setVisible(true);  // Show all base layers

    // Check current state
    if (baseMap.isVisible()) {
      console.log('Base map is visible');
    }

    Working with layer groups:

    // Show only roads and borders
    const baseMap = await BaseMapModule.get(map, {
      layerGroupsFilter: {
        mode: 'include',
        names: ['roadLines', 'roadLabels', 'borders']
      }
    });

    // Hide buildings and labels
    baseMap.setVisible(false, {
      layerGroups: {
        mode: 'include',
        names: ['buildings2D', 'buildings3D', 'placeLabels']
      }
    });

    // Show only water and land
    baseMap.setVisible(true, {
      layerGroups: {
        mode: 'include',
        names: ['water', 'land']
      }
    });

    Event handling:

    const baseMap = await BaseMapModule.get(map);

    // Listen for clicks on base map features
    baseMap.events.on('click', (feature, lngLat) => {
      console.log('Clicked base map feature:', feature);
    });

    // Remove event listeners
    baseMap.events.off('click');

    Hierarchy (View Summary)

    Index

    Accessors

    events sourceAndLayerIDs

    Methods

    applyConfig getConfig isVisible resetConfig setVisible waitUntilModuleReady get

    Accessors

    • Gets the events interface for this module to handle user interactions.

      Returns EventsModule<MapGeoJSONFeature>

      An EventsModule instance for registering event handlers.

      Supported Events:

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

      Event Handler Signature:

      (feature: MapGeoJSONFeature, lngLat: LngLat, allFeatures: MapGeoJSONFeature[]) => void

      Register click handler:

      baseMap.events.on('click', (feature, lngLat) => {
        console.log('Clicked on:', feature.properties);
        console.log('At coordinates:', lngLat);
      });

      Multiple event types:

      // Show tooltip on hover
      baseMap.events.on('hover', (feature) => {
        showTooltip(feature.properties.name);
      });

      // Handle clicks
      baseMap.events.on('click', (feature) => {
        selectFeature(feature.id);
      });

      // Clean up
      baseMap.events.off('hover');
      baseMap.events.off('click');
    • 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: BaseMapModuleConfig | 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

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

    • Checks if any base map layers are currently visible.

      Returns boolean

      true if at least one base map layer is visible, false if all are hidden.

      This checks the actual visibility state of layers in the map, not just the module's configuration setting.

      if (baseMap.isVisible()) {
        console.log('Base map is rendered');
      } else {
        console.log('Base map is hidden');
      }

    • 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 base map layers.

      Parameters

      • visible: boolean

        true to show layers, false to hide them.

      • Optionaloptions: { layerGroups?: BaseMapLayerGroups }

        Optional settings for fine-grained control.

        • OptionallayerGroups?: BaseMapLayerGroups

          Target specific layer groups instead of all layers.

      Returns void

      Behavior:

      • Without options.layerGroups: Affects all base map layers
      • With options.layerGroups: Affects only specified layer groups
      • Changes are applied immediately if map is ready

      Layer Groups: Available groups: land, water, borders, buildings2D, buildings3D, houseNumbers, roadLines, roadLabels, roadShields, placeLabels, smallerTownLabels, cityLabels, capitalLabels, stateLabels, countryLabels

      Show/hide all layers:

      baseMap.setVisible(false); // Hide everything
      baseMap.setVisible(true);  // Show everything

      Control specific groups:

      // Hide only buildings
      baseMap.setVisible(false, {
        layerGroups: {
          mode: 'include',
          names: ['buildings2D', 'buildings3D']
        }
      });

      // Show everything except labels
      baseMap.setVisible(true, {
        layerGroups: {
          mode: 'exclude',
          names: ['placeLabels', 'cityLabels', 'countryLabels']
        }
      });

      Toggle visibility:

      const isVisible = baseMap.isVisible();
      baseMap.setVisible(!isVisible); // Toggle

    • Asynchronously retrieves a BaseMapModule instance for the given map.

      This is the recommended way to create a BaseMapModule. It ensures the map is fully loaded before initializing the module.

      Parameters

      Returns Promise<BaseMapModule>

      A promise that resolves to the initialized BaseMapModule.

      Initialization:

      • Waits for map to be ready before creating module
      • Validates that required sources exist in the map style
      • Applies initial configuration if provided

      Configuration Options:

      • visible: Initial visibility state
      • layerGroupsFilter: Which layer groups to include/exclude
      • layerGroupsVisibility: Fine-grained visibility per group

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

      Default initialization:

      const baseMap = await BaseMapModule.get(map);

      With configuration:

      const baseMap = await BaseMapModule.get(map, {
        visible: true,
        layerGroupsFilter: {
          mode: 'exclude',
          names: ['buildings3D', 'houseNumbers']
        }
      });

      Show only specific groups:

      const baseMap = await BaseMapModule.get(map, {
        layerGroupsFilter: {
          mode: 'include',
          names: ['water', 'land', 'borders']
        },
        visible: true
      });

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods