API Reference

All parts of the component set you can use and combine to build your map.

<ng-map [center]="[-74.006, 40.7128]" [zoom]="11">
  <ng-map-controls />

  <ng-map-marker [longitude]="-74.006" [latitude]="40.7128">
    <ng-marker-content>
      <div class="size-4 rounded-full bg-blue-500"></div>
      <ng-marker-label position="top">New York</ng-marker-label>
    </ng-marker-content>
    <ng-marker-tooltip>Hover content</ng-marker-tooltip>
    <ng-marker-popup>Click content</ng-marker-popup>
  </ng-map-marker>

  <ng-map-popup [longitude]="-74" [latitude]="40.7">Standalone popup</ng-map-popup>
  <ng-map-route [coordinates]="coordinates" />
  <ng-map-arc [data]="arcs" />
  <ng-map-geojson [data]="geojson" />
  <ng-map-cluster-layer [data]="points" />
  <ng-map-heatmap [data]="points" weightProperty="mag" />
  <ng-map-raster-source id="radar" [tiles]="radarTiles" [opacity]="0.7" />
  <ng-map-vector-source id="parcels" url="pmtiles://https://example.com/parcels.pmtiles" />
  <ng-map-image-overlay [url]="imageUrl" [coordinates]="corners" />
</ng-map>

ng-map

The root container component that initializes MapLibre GL and provides context to child components. Automatically handles theme switching between light and dark modes.

ng-map-controls

Renders map control buttons: zoom, compass, locate, and fullscreen. Must be used inside ng-map.

ng-map-marker

A container for marker-related components. Provides context for its children and handles marker positioning.

ng-marker-content

Renders the visual content of a marker via content projection. If left empty, a default blue dot is rendered; it follows conditional content (shown while nothing is projected). Must be used inside ng-map-marker.

ng-marker-label

An always-visible text label above or below the marker. Must be used inside ng-marker-content.

ng-marker-popup

A popup attached to the marker that opens on click. Must be used inside ng-map-marker. Keyboard: the marker becomes a focusable role=button with aria-haspopup=dialog (unless you set them), Enter/Space opens it, focus moves into the popup, and Escape closes it, stops propagation and returns focus to the marker. Avoid your own <button> inside ng-marker-content (nested interactive content).

ng-marker-tooltip

A tooltip that appears on marker hover and keyboard focus (Escape or blur closes it; the marker becomes a tab stop). Must be used inside ng-map-marker.

ng-map-popup

A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside ng-map. Keyboard: focus moves into the popup when it opens, and Escape inside it closes it (stops propagation, so a host dialog stays open).

ng-map-route

Renders a line/route from the given coordinates. Must be used inside ng-map. Supports click and hover interactions, an active (highlighted) state and a covered-progress line via child ng-route-progress / ng-route-marker components.

ng-route-progress

Draws the covered part of the parent ng-map-route, as set by its progress input (computed by cumulative distance along the line). Use inside ng-map-route.

ng-route-marker

A marker placed along the parent ng-map-route. Project ng-marker-content (and label, popup, tooltip) into it. Created once and moved as progress or coordinates change.

ng-map-arc

Renders curved lines between coordinate pairs using quadratic Bézier interpolation, with longitude unwrapping across the antimeridian. Must be used inside ng-map.

ng-map-geojson

Renders GeoJSON polygons and lines with theme-aware monochrome defaults and declarative feature-state hover. Accepts a URL or an inline GeoJSON object. Generic over the feature properties: MapGeoJSONComponent<P>, with P inferred from data. Must be used inside ng-map.

ng-map-cluster-layer

Renders clustered points with MapLibre GL native clustering. Automatically styles cluster circles by point count, zooms in on cluster click. Generic over the feature properties: MapClusterLayerComponent<P>, with P inferred from data. Must be used inside ng-map.

ng-map-heatmap

Renders GeoJSON points as a MapLibre heatmap layer with a theme-aware default gradient. Generic over the feature properties: MapHeatmapComponent<P>, with P inferred from data. Must be used inside ng-map.

ng-map-raster-source

Raster tile source (XYZ, TMS, WMS) plus the raster layer that draws it. Source and layer are re-added after a theme switch. Must be used inside ng-map.

ng-map-vector-source

Vector tile source (MVT, TileJSON or pmtiles://). Adds the source only: draw it with layers that reference it by id and wait for it with MapContextService.hasSource(id). ng-mapcn does not depend on pmtiles; register the protocol yourself with maplibregl.addProtocol. When torn down or the style reloads it removes every layer still using the source, then the source: gate your layers on hasSource(id). tiles vs url mode is fixed at creation. Must be used inside ng-map.

ng-map-image-overlay

Georeferenced image pinned to four corner coordinates, drawn as a raster layer. Must be used inside ng-map.

ng-map-fill-extrusion

3D extrusion of polygons (fill-extrusion layer), e.g. 3D buildings. Creates only the layer: the source is a basemap source or one added by a source component or the application, and the layer waits for it. Re-added after a theme switch. Must be used inside ng-map.

ng-map-terrain

3D terrain from a raster-dem source (map.setTerrain) with an optional hillshade layer. The terrain is style-level state: it is re-applied after a theme switch and disabled on teardown. One terrain per map. Must be used inside ng-map.

ng-map-draw

Draws, selects and edits points, lines and polygons on terra-draw. Lives in the optional ng-mapcn/draw entry point (import { MapDrawComponent } from 'ng-mapcn/draw') and needs the terra-draw and terra-draw-maplibre-gl-adapter peer dependencies. A theme switch (setStyle) stops and restarts terra-draw with the same features and mode. Must be used inside ng-map.

Component-scoped service provided by ng-map - the Angular equivalent of mapcn's useMap() hook. Inject it in any component projected inside ng-map to access the raw map.

Sets the app-wide default basemap through the MAP_DEFAULT_STYLES token. Every ng-map without its own styles input (and without blank) uses it; pass a signal to swap the basemap at runtime. Precedence: styles → blank → provideMapStyles() → Carto default.

import { inject } from '@angular/core';
import { provideMapStyles } from 'ng-mapcn';

export const appConfig: ApplicationConfig = {
  providers: [
    // Static config...
    provideMapStyles({
      light: 'https://tiles.openfreemap.org/styles/positron',
      dark: 'https://tiles.openfreemap.org/styles/dark',
    }),

    // ...or a signal, so the basemap can be switched at runtime
    provideMapStyles(() => inject(BasemapService).styles),
  ],
};

Translates the control buttons, the loader and the popup close button through the MAP_LABELS token. Partial labels merge over the English defaults; pass a signal to follow the active locale. A labels input on ng-map, ng-map-controls and ng-map-popup overrides it per component.

import { inject } from '@angular/core';
import { provideMapLabels } from 'ng-mapcn';

export const appConfig: ApplicationConfig = {
  providers: [
    // Static (partial) labels merge over the English defaults...
    provideMapLabels({
      zoomIn: 'Aproximar',
      zoomOut: 'Afastar',
      resetNorth: 'Apontar para o norte',
      locate: 'Minha localização',
      fullscreen: 'Tela cheia',
      loading: 'Carregando mapa',
      closePopup: 'Fechar',
    }),

    // ...or a signal, so the labels follow the active locale
    provideMapLabels(() => inject(I18nService).mapLabels),
  ],
};

// Per component: <ng-map-controls [labels]="{ zoomIn: 'Acercar' }" />