MapLibre¶

Usage¶

MapLibre exposes its map, controls, sources, and layers as composable Angular components and directives. Applications remain responsible for configuring and composing the map.

When to use¶

• When direct access to MapLibre features, sources, and layers is required.
• When map controls and behavior need to be composed for a specific use case.
• When vector-map rendering and MapLibre's ecosystem are preferred.
• When 3D features such as pitched views, extruded buildings, or a globe are required.
• When the high-level Element Maps component does not provide enough flexibility.

Code¶

See the ngx-maplibre-gl documentation and the MapLibre GL JS documentation for the complete APIs and configuration options.

npm install --save @siemens/element-ng @siemens/map-styles @siemens/element-translate-ng
npm install --save @maplibre/ngx-maplibre-gl maplibre-gl

Configure the MapLibre worker¶

MapLibre GL JS 6 loads its web worker from a separate file. Add the worker and its shared module to the application assets in angular.json:

{
  "architect": {
    "build": {
      "options": {
        "assets": [
          {
            "glob": "maplibre-gl-{worker,shared}.mjs",
            "input": "node_modules/maplibre-gl/dist",
            "output": "/assets/maplibre/"
          }
        ]
      }
    }
  }
}

Register the worker in the application configuration before creating a map:

import { ApplicationConfig } from '@angular/core';
import { provideMaplibreWorker } from '@maplibre/ngx-maplibre-gl/config';

export const appConfig: ApplicationConfig = {
  providers: [provideMaplibreWorker('assets/maplibre/maplibre-gl-worker.mjs')]
};

Apply Element control styles¶

Import the Element MapLibre stylesheet in the application's global stylesheet. It provides the required MapLibre layout styles and applies Element styling to controls, popovers, markers, and other map UI.

@use '@siemens/element-ng/maplibre/styles';

Use this stylesheet instead of importing maplibre-gl/dist/maplibre-gl.css separately.

Apply the Element map style¶

injectSiMapStyle() creates a signal containing the Element MapLibre style. Pass a MapTiler API key to the function and bind the signal value to the map's mapStyle input. The style updates automatically when the Element theme changes.

The function must be called in an Angular injection context, such as a component field initializer.

import { Component } from '@angular/core';
import { MapComponent } from '@maplibre/ngx-maplibre-gl';
import { injectSiMapStyle } from '@siemens/element-ng/maplibre';

@Component({
  selector: 'app-map',
  imports: [MapComponent],
  template: '<mgl-map class="h-100" [mapStyle]="mapStyle()" />'
})
export class AppMapComponent {
  protected readonly mapStyle = injectSiMapStyle('REPLACE_WITH_YOUR_MAPTILER_KEY');
}

Apply translations¶

injectSiMapTranslations() creates a signal containing translated MapLibre locale strings. It uses the configured Element translation service and updates when the active language changes. Bind the signal value to the map's locale input:

import { Component } from '@angular/core';
import { MapComponent } from '@maplibre/ngx-maplibre-gl';
import { injectSiMapTranslations } from '@siemens/element-ng/maplibre';

@Component({
  selector: 'app-map',
  imports: [MapComponent],
  template: '<mgl-map class="h-100" [locale]="mapTranslations()" />'
})
export class AppMapComponent {
  protected readonly mapTranslations = injectSiMapTranslations();
}

MapLibre example¶

The following example combines the Element map style and translations with MapLibre controls.

Cluster example¶

The following example uses SiClusterSourceComponent to cluster GeoJSON points and SiStatusMarkerComponent for unclustered markers. Cluster markers show the number of contained points and their distribution by group or status.

3D buildings example¶

MapLibre GL renders maps with WebGL, so the camera can be pitched and vector-tile buildings can be extruded into 3D.

The example pitches the map and adds a fill-extrusion layer on the OpenMapTiles building source. Building height animates in between zoom 15 and 16 using the render_height and render_min_height properties from the tiles.