# ng-mapcn — full reference

> Angular port of [mapcn](https://www.mapcn.dev) — composable MapLibre GL v6 map components in the spirit of shadcn/ui. Standalone, signals-first, OnPush, SSR-safe, theme-aware. Carto basemaps by default, so no API key is required. Distributed both as an npm package and as copy-paste sources via `ng add` (you own the code).

Version: 22.0.0-beta.7 · License: MIT · Docs: https://ng-mapcn.vercel.app · Repository: https://github.com/juanvieiraprado99/ng-mapcn

## Installation

### Copy-paste (recommended, shadcn-style)

```bash
ng add ng-mapcn
```

Adds `maplibre-gl`, registers its CSS, appends the required `.maplibregl-popup-*` overrides and copies the component sources into `src/app/components/ui/map` (customize with `--path`).

### npm package

```bash
npm install ng-mapcn maplibre-gl
```

```scss
// global styles.scss
@use 'ng-mapcn/src/lib/styles/index' as *;  // tokens + utilities
@use 'ng-mapcn/styles.scss' as *;           // required popup overrides
@import 'maplibre-gl/dist/maplibre-gl.css'; // MapLibre base CSS
```

The `.maplibregl-popup-*` overrides are **required** — MapLibre injects its own popup chrome, which must be neutralized for popups and tooltips to render correctly.

### Agent skill

```bash
npx skills add juanvieiraprado99/ng-mapcn
```

Installs the ng-mapcn agent skill (https://github.com/juanvieiraprado99/ng-mapcn/tree/main/skills/ng-mapcn) with the [skills.sh](https://skills.sh) CLI, so coding agents use the real API: selectors, inputs, outputs, setup, recipes and troubleshooting.

## Quick start

```html
<ng-map [center]="[-46.63, -23.55]" [zoom]="10">
  <ng-map-controls position="bottom-right" [showZoom]="true" [showCompass]="true" />

  <ng-map-marker [longitude]="-46.63" [latitude]="-23.55" [draggable]="true">
    <ng-marker-content><!-- empty = default blue dot --></ng-marker-content>
    <ng-marker-popup><strong>São Paulo</strong></ng-marker-popup>
    <ng-marker-tooltip>Olá!</ng-marker-tooltip>
  </ng-map-marker>

  <ng-map-route [coordinates]="lineCoords" color="#4285F4" [width]="3" />
</ng-map>
```

## Component anatomy

Every part of the component set, and how they nest:

```html
<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>
```

## Components

### 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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `center` | `[number, number]` | `[0, 0]` | Initial center coordinates as [longitude, latitude]. |
| `zoom` | `number` | `2` | Initial zoom level of the map. |
| `styles` | `MapStylesConfig` | `CARTO` | Custom style URLs or style objects for light and dark themes. |
| `blank` | `boolean` | `false` | Swaps the basemap for a transparent, tile-less canvas. Add your own layers on top. |
| `projection` | `ProjectionSpecification` | — | Map projection, e.g. { type: 'globe' }. |
| `theme` | `'light' \| 'dark' \| 'auto'` | `'auto'` | Force a theme, or 'auto' to follow the dark/light class on <html>. |
| `loading` | `boolean` | `false` | Shows the loading overlay. |
| `labels` | `Partial<MapLabels>` | — | Label overrides (loading), merged over provideMapLabels() and the English defaults. |
| `viewport` | `Partial<MapViewport>` | — | Controlled viewport ({ center, zoom, bearing, pitch }). Pair with viewportChange. |
| `fitBounds` | `MapFitBoundsOptions` | — | Fits the camera to bounds ({ bounds?, padding?, maxZoom?, duration?, animate? }). Without bounds it fits the union of the children's data (markers, GeoJSON, routes, arcs, clusters, heatmaps). Runs after load and refits only when the bounds change; the first fit never animates; maxZoom defaults to 16. A draggable marker bound to signals refits while dragged: pass explicit bounds for that case. Imperative form: MapContextService.fitBounds(). |
| `options` | `Omit<MapOptions, 'container' \| 'style'>` | — | Extra MapLibre MapOptions (scrollZoom, dragRotate, …) passed to the map constructor. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `viewportChange` | `MapViewport` | — | Emits on every viewport change (move, zoom, rotate, pitch). |
| `mapReady` | `Map` | — | Emits the raw maplibre-gl Map instance once loaded. |
| `mapClick` | `MapMouseEvent` | — | Emits when the map is clicked. |
| `mapError` | `Error` | — | Emits when the map fails to initialize or load. |

### MapControls

`ng-map-controls`

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

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `position` | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'` | `'bottom-right'` | Corner of the map to place the controls in. |
| `showZoom` | `boolean` | `true` | Show zoom in/out buttons. |
| `showCompass` | `boolean` | `false` | Show compass button (resets bearing). |
| `showLocate` | `boolean` | `false` | Show geolocate button. |
| `showFullscreen` | `boolean` | `false` | Show fullscreen toggle button. |
| `labels` | `Partial<MapLabels>` | — | Label overrides (zoomIn, zoomOut, resetNorth, locate, fullscreen), merged over provideMapLabels() and the English defaults. |
| `className` | `string` | — | Extra space-separated classes added to the rendered .ng-controls element. Reactive; the built-in class is always kept. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `locateChange` | `{ longitude: number; latitude: number }` | — | Emits the user position after a successful locate. |
| `locateError` | `GeolocationPositionError \| Error` | — | Emits when locating fails (denied, timeout) or when the browser has no geolocation. |

### MapMarker

`ng-map-marker`

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

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `longitude` | `number` | `required` | Longitude coordinate of the marker. |
| `latitude` | `number` | `required` | Latitude coordinate of the marker. |
| `draggable` | `boolean` | `false` | Allows the marker to be dragged. |
| `offset` | `PointLike` | — | Pixel offset applied to the marker element. |
| `rotation` | `number` | `0` | Rotation of the marker in degrees. |
| `anchor` | `PositionAnchor` | — | Part of the marker element positioned at the coordinates. |
| `rotationAlignment` | `'map' \| 'viewport' \| 'auto'` | `'auto'` | How the marker rotates with the map. |
| `pitchAlignment` | `'map' \| 'viewport' \| 'auto'` | `'auto'` | How the marker tilts with the map pitch. |
| `ariaLabel` | `string` | — | Accessible name of the marker (aria-label). Interactive markers whose content has no text fall back to labels.marker ('Map marker'); a static labelled marker gets role="img". |
| `labels` | `Partial<MapLabels>` | — | Label overrides (marker), merged over provideMapLabels() and the English defaults. |
| `keyboardStep` | `number` | `10` | Pixels a draggable marker moves per arrow key press. |
| `keyboardStepLarge` | `number` | `50` | Pixels per arrow key press while Shift is held. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `markerClick` | `MouseEvent` | — | Emits when the marker is clicked, or when Enter or Space (on keyup) is pressed on the focused marker, also with ng-marker-popup. Give icon-only clickable markers their own ariaLabel. A marker with this handler becomes a role=button tab stop. |
| `markerMouseEnter` | `MouseEvent` | — | Emits when the pointer enters the marker. |
| `markerMouseLeave` | `MouseEvent` | — | Emits when the pointer leaves the marker. |
| `dragStart` | `{ lng: number; lat: number }` | — | Emits when dragging starts. |
| `drag` | `{ lng: number; lat: number }` | — | Emits continuously while dragging. |
| `dragEnd` | `{ lng: number; lat: number }` | — | Emits the final position after dragging. |

### MarkerContent

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `className` | `string` | — | Extra space-separated classes added to the rendered .ng-marker-content element. Reactive; the built-in class is always kept. |

### MarkerLabel

`ng-marker-label`

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

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `position` | `'top' \| 'bottom'` | `'top'` | Side of the marker the label appears on. |

### MarkerPopup

`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).

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `closeButton` | `boolean` | `false` | Shows a close button in the popup. |
| `offset` | `Offset` | — | Pixel offset from the marker. Reconciled live via setOffset; MapLibre's default when unset. |
| `anchor` | `PositionAnchor` | — | Which side of the marker the popup anchors to. Applied at creation only. |
| `maxWidth` | `string` | `'none'` | CSS max-width of the popup container. Reconciled live via setMaxWidth. |
| `closeOnClick` | `boolean` | `false` | Closes the popup when the map is clicked. Applied at creation only. |
| `labels` | `Partial<MapLabels>` | — | Label overrides (closePopup), merged over provideMapLabels() and the English defaults. |
| `className` | `string` | — | Extra space-separated classes added to the rendered .ng-popup-card element. Reactive; the built-in class is always kept. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `popupClose` | `void` | — | Emits when the popup closes. |

### MarkerTooltip

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `offset` | `Offset` | `16` | Pixel distance between the marker and the tooltip. |
| `anchor` | `PositionAnchor` | — | Which side of the coordinates the tooltip anchors to. |
| `className` | `string` | — | Extra space-separated classes added to the rendered .ng-tooltip-pill element. Reactive; the built-in class is always kept. |

### MapPopup

`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).

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `longitude` | `number` | `required` | Longitude coordinate of the popup. |
| `latitude` | `number` | `required` | Latitude coordinate of the popup. |
| `closeButton` | `boolean` | `false` | Shows a close button in the popup. |
| `offset` | `Offset` | `16` | Pixel offset of the popup. |
| `maxWidth` | `string` | `'none'` | CSS max-width of the popup container. |
| `closeOnClick` | `boolean` | `true` | Closes the popup when the map is clicked. Applied at creation only. Set false for popups that follow the hover. |
| `labels` | `Partial<MapLabels>` | — | Label overrides (closePopup), merged over provideMapLabels() and the English defaults. |
| `className` | `string` | — | Extra space-separated classes added to the rendered .ng-popup-card element. Reactive; the built-in class is always kept. Pass ng-popup-passthrough to make the whole popup non-interactive (pointer-events: none), so a hover popup does not capture the cursor and close itself. |
| `open` | `boolean` | `true` | Whether the popup is shown. Two-way bindable with [(open)]: closing it writes false, setting true opens it again at the current position. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `popupClose` | `void` | — | Emits when the popup closes, by the user or by setting open to false. |
| `openChange` | `boolean` | — | Emits the new open state (the [(open)] binding). |

### MapRoute

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `coordinates` | `[number, number][]` | `required` | Array of [longitude, latitude] points forming the line. |
| `id` | `string` | `auto` | Optional stable id for the underlying source/layer. |
| `color` | `string` | `'#4285F4'` | Line color. |
| `width` | `number` | `3` | Line width in pixels. |
| `opacity` | `number` | `0.8` | Line opacity. |
| `dashArray` | `number[]` | — | Dash pattern, e.g. [2, 2]. |
| `interactive` | `boolean` | `true` | Enables pointer events on the line. |
| `beforeId` | `string` | — | Id of an existing layer to insert the route (and its progress line) below. Applied at creation only. |
| `progress` | `number` | — | Covered fraction of the route (0 to 1). Drawn by a child ng-route-progress and followed by ng-route-marker at="progress". |
| `active` | `boolean` | `false` | Highlights the route: the active* inputs override the base paint while true. |
| `activeColor` | `string` | — | Line color while active. Falls back to color. |
| `activeWidth` | `number` | — | Line width while active. Falls back to width. |
| `activeOpacity` | `number` | — | Line opacity while active. Falls back to opacity. |
| `activeDashArray` | `number[]` | — | Dash pattern while active. Falls back to dashArray. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `routeClick` | `MapMouseEvent` | — | Emits when the route is clicked. |
| `routeMouseEnter` | `MapMouseEvent` | — | Emits when the pointer enters the route (the cursor becomes a pointer). |
| `routeMouseLeave` | `MapMouseEvent` | — | Emits when the pointer leaves the route. |

### RouteProgress

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `color` | `string` | `'#22c55e'` | Color of the covered line. |
| `width` | `number` | `route width` | Width of the covered line in pixels. |
| `opacity` | `number` | `1` | Opacity of the covered line. |
| `dashArray` | `number[]` | — | Dash pattern of the covered line. |

### RouteMarker

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `at` | `'start' \| 'end' \| 'progress' \| number` | `'start'` | Position on the route: its start, end, the current progress, or a fraction between 0 and 1 of the total distance. |

### MapArc

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `data` | `MapArcDatum[]` | `required` | Arcs to draw: { id, from: [lng, lat], to: [lng, lat] }. Extra properties are exposed to paint expressions. |
| `id` | `string` | `auto` | Optional stable id for the underlying source/layer. |
| `curvature` | `number` | `0.2` | How much the arc bends. |
| `samples` | `number` | `64` | Number of interpolation points per arc. |
| `paint` | `LineLayerSpecification["paint"]` | — | MapLibre line paint properties. |
| `layout` | `LineLayerSpecification["layout"]` | — | MapLibre line layout properties. |
| `hoverPaint` | `LineLayerSpecification["paint"]` | — | Paint overrides applied to the hovered arc via feature-state. |
| `interactive` | `boolean` | `true` | Enables pointer events (adds an invisible hit layer). |
| `beforeId` | `string` | — | Insert the layer before this layer id. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `arcClick` | `MapArcEvent` | — | Emits { arc, longitude, latitude, originalEvent } when an arc is clicked. |
| `arcHover` | `MapArcEvent \| null` | — | Emits on hover; null when the pointer leaves. |

### MapGeoJSON

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `data` | `MapGeoJSONData<P>` | `required` | GeoJSON object or URL string. P types the featureClick/featureHover payloads. |
| `id` | `string` | `auto` | Optional stable id for the underlying source/layer. |
| `promoteId` | `string` | — | Feature property used as feature id — required for hover feature-state. |
| `fillPaint` | `FillLayerSpecification["paint"]` | `theme mono` | Fill paint properties. |
| `linePaint` | `LineLayerSpecification["paint"]` | `theme mono` | Outline paint properties. |
| `fillHoverPaint` | `FillLayerSpecification["paint"]` | — | Fill paint overrides applied to the hovered feature. |
| `interactive` | `boolean` | `false` | Enables pointer events and hover tracking. |
| `beforeId` | `string` | — | Insert the layers before this layer id. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `featureClick` | `MapGeoJSONEvent<P>` | — | Emits { feature, longitude, latitude, originalEvent } on click. |
| `featureHover` | `MapGeoJSONEvent<P> \| null` | — | Emits on hover; null when the pointer leaves. |

### MapClusterLayer

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `data` | `string \| FeatureCollection<Point, P>` | `required` | GeoJSON points (object or URL string). P types the pointClick payload. |
| `id` | `string` | `auto` | Optional stable id prefix for the source and layers: cluster-source-<id>, clusters-<id>, cluster-count-<id>, unclustered-point-<id>. Changing it re-creates them. |
| `beforeId` | `string` | — | Insert the cluster layers before this layer id. Applied at creation only. |
| `clusterMaxZoom` | `number` | `14` | Max zoom at which points are clustered. |
| `clusterRadius` | `number` | `50` | Cluster radius in pixels. |
| `clusterColors` | `[string, string, string]` | `['#22c55e', '#eab308', '#ef4444']` | Circle colors for small/medium/large clusters. ng-mapcn defaults to green/yellow/red; mapcn uses ['#3b82f6', '#1d4ed8', '#1e3a8a']. |
| `clusterThresholds` | `[number, number]` | `[100, 750]` | Point-count thresholds between color tiers. |
| `pointColor` | `string` | `'#3b82f6'` | Color of unclustered points. |
| `zoomOnClusterClick` | `boolean` | `true` | Zooms into a cluster when it is clicked. |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `pointClick` | `ClusterPointClickEvent<P>` | — | Emits { feature, coordinates } when an unclustered point is clicked. |
| `clusterClick` | `ClusterClickEvent` | — | Emits { clusterId, coordinates, pointCount } when a cluster is clicked. |

### MapHeatmap

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `data` | `string \| FeatureCollection<Point, P>` | `required` | GeoJSON points (object or URL string). |
| `id` | `string` | `auto` | Optional stable id prefix for the source and layer: heatmap-source-<id>, heatmap-layer-<id>. Changing it re-creates them. |
| `beforeId` | `string` | — | Insert the layer before this layer id. Applied at creation only. |
| `weightProperty` | `string` | — | Numeric feature property used as the point weight. Without it every point weighs the same. |
| `weightRange` | `[number, number]` | `[0, 1]` | [min, max] of weightProperty, mapped linearly to a weight of 0..1. |
| `radius` | `number \| expression` | `30` | Influence radius of each point in pixels. Accepts MapLibre expressions. |
| `intensity` | `number \| expression` | `1` | Global intensity multiplier. Accepts MapLibre expressions. |
| `opacity` | `number \| expression` | `1` | Layer opacity. Accepts MapLibre expressions. |
| `gradient` | `HeatmapGradient` | `theme default` | Color stops [density 0..1, color]. Sorted, with a transparent stop at 0 prepended when missing. Defaults to defaultHeatmapGradients for the resolved theme. |
| `minZoom` | `number` | `0` | Minimum zoom at which the heatmap is rendered. |
| `maxZoom` | `number` | `24` | Zoom from which the heatmap is no longer rendered (e.g. to hand over to a point layer). |
| `paint` | `HeatmapLayerSpecification["paint"]` | — | Escape hatch: heatmap paint properties merged last. |

### MapRasterSource

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | `auto` | MapLibre source id, used verbatim (other components reference it as source: id). The layer is raster-layer-<id>. Changing it re-creates both. |
| `tiles` | `string[]` | — | Tile URL templates ({z}/{x}/{y}, {bbox-epsg-3857} for WMS). Updated in place with setTiles. |
| `url` | `string` | — | TileJSON URL, instead of tiles (takes precedence). Updated in place with setUrl. |
| `tileSize` | `number` | `256` | Tile size in pixels. Applied at creation. |
| `minzoom` | `number` | `0` | Minimum tile zoom. Applied at creation. |
| `maxzoom` | `number` | `22` | Maximum tile zoom. Applied at creation. |
| `attribution` | `string` | — | Attribution for the map attribution control. Applied at creation. |
| `bounds` | `[number, number, number, number]` | — | [west, south, east, north] limit of the tiles. Applied at creation. |
| `scheme` | `'xyz' \| 'tms'` | `'xyz'` | Tile addressing scheme. Applied at creation. |
| `opacity` | `number \| expression` | `1` | Raster layer opacity (raster-opacity). |
| `visible` | `boolean` | `true` | Whether the layer is drawn; the source stays loaded when hidden. |
| `beforeId` | `string` | — | Insert the layer before this layer id. Applied at creation only. |
| `paint` | `RasterLayerSpecification["paint"]` | — | Escape hatch: raster paint properties merged last. |

### MapVectorSource

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | `auto` | MapLibre source id, used verbatim; layers reference it as source: id. Announced through MapContextService.hasSource(id) while it exists. Changing it re-creates the source. |
| `tiles` | `string[]` | — | Tile URL templates. Updated in place with setTiles. |
| `url` | `string` | — | TileJSON URL or pmtiles://<archive url> (register the pmtiles protocol first), instead of tiles. Updated in place with setUrl. |
| `minzoom` | `number` | `0` | Minimum tile zoom. Applied at creation. |
| `maxzoom` | `number` | `22` | Maximum tile zoom. Applied at creation. |
| `attribution` | `string` | — | Attribution for the map attribution control. Applied at creation. |
| `bounds` | `[number, number, number, number]` | — | [west, south, east, north] limit of the tiles. Applied at creation. |
| `scheme` | `'xyz' \| 'tms'` | `'xyz'` | Tile addressing scheme. Applied at creation. |
| `promoteId` | `string \| Record<string, string>` | — | Feature property (or per source-layer map) used as the feature id, which enables feature-state on vector tiles. Applied at creation. |

### MapImageOverlay

`ng-map-image-overlay`

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

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | `auto` | MapLibre image source id, used verbatim. The layer is image-layer-<id>. Changing it re-creates both. |
| `url` | `string` | `required` | Image URL. Changing it calls updateImage on the live source. |
| `coordinates` | `ImageOverlayCoordinates` | `required` | Four [lng, lat] corners, clockwise from the top-left. Changing them calls setCoordinates. |
| `opacity` | `number \| expression` | `1` | Layer opacity (raster-opacity). |
| `visible` | `boolean` | `true` | Whether the layer is drawn. |
| `beforeId` | `string` | — | Insert the layer before this layer id. Applied at creation only. |
| `paint` | `RasterLayerSpecification["paint"]` | — | Escape hatch: raster paint properties merged last (e.g. raster-fade-duration: 0 to avoid a flash on url change). |

### MapFillExtrusion

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | `auto` | Layer id prefix; the layer is fill-extrusion-layer-<id>. Changing it re-creates the layer. |
| `source` | `string` | `Carto basemap source` | Id of the source to extrude: a tile source component, an application source or a basemap source. Without it, the Carto basemap's building source is used ('protomaps', or 'carto' in the earlier styles). The layer is added once map.getSource(source) exists. |
| `sourceLayer` | `string` | `'buildings' for 'protomaps', 'building' for 'carto', else none` | Layer of a vector source. Omit for GeoJSON sources. |
| `heightProperty` | `string` | `'height' for 'protomaps', else 'render_height'` | Feature property with the height in meters. |
| `baseProperty` | `string` | `'min_height' for 'protomaps', else 'render_min_height'` | Feature property with the base height in meters. |
| `color` | `string \| expression` | `theme gray` | Fill color; defaults to a theme-aware gray (defaultExtrusionColors). |
| `opacity` | `number` | `0.8` | Layer opacity, 0..1. |
| `minZoom` | `number` | `14` | Minimum zoom at which the extrusion is drawn (the Carto tiles stop at 14). |
| `maxZoom` | `number` | `24` | Zoom from which the extrusion is no longer drawn. |
| `filter` | `FilterSpecification \| null` | `['!=', ['get', 'hide_3d'], true]` | MapLibre filter, updated with setFilter. null removes the default filter. |
| `beforeId` | `string` | — | Insert the layer before this layer id. Applied at creation only. |
| `paint` | `FillExtrusionLayerSpecification["paint"]` | — | Escape hatch: fill-extrusion paint properties merged last. |

### MapTerrain

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `id` | `string` | `auto` | Id prefix: DEM source terrain-source-<id>, hillshade source terrain-hillshade-source-<id>, hillshade layer terrain-hillshade-<id>. Changing it re-creates all. |
| `tiles` | `string[]` | `public Terrarium tiles` | Elevation tile URL templates. Applied at creation. |
| `url` | `string` | — | TileJSON URL, instead of tiles (takes precedence). Applied at creation. |
| `encoding` | `'terrarium' \| 'mapbox'` | `'terrarium'` | Encoding of the elevation tiles. Applied at creation. |
| `tileSize` | `number` | `256` | Tile size in pixels. Applied at creation. |
| `minzoom` | `number` | — | Minimum zoom of the elevation tiles. Applied at creation. |
| `maxzoom` | `number` | `15 for the default tiles` | Maximum zoom of the elevation tiles. Applied at creation. |
| `attribution` | `string` | `Mapzen / AWS for the default tiles` | Attribution for the map attribution control. Applied at creation. |
| `exaggeration` | `number` | `1` | How tall the terrain looks. Changing it calls setTerrain again. |
| `hillshade` | `boolean` | `false` | Draw a hillshade layer (with its own DEM source). Added and removed on toggle; the terrain is untouched. |
| `hillshadeExaggeration` | `number` | — | Hillshade intensity, 0..1 (MapLibre default 0.5). |
| `hillshadeShadowColor` | `string` | — | Hillshade color of the shaded slopes. |
| `hillshadeHighlightColor` | `string` | — | Hillshade color of the lit slopes. |
| `hillshadeAccentColor` | `string` | — | Hillshade accent color for steep slopes. |
| `hillshadePaint` | `HillshadeLayerSpecification["paint"]` | — | Escape hatch: hillshade paint properties merged last. |
| `beforeId` | `string` | — | Insert the hillshade layer before this layer id. Applied when the layer is created only. |

### MapDraw

`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.

**Inputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `modes` | `('point' \| 'line' \| 'polygon')[]` | `all three` | Shapes the user can draw. Changing it restarts terra-draw with the same features and drops an unfinished shape. |
| `mode` | `'point' \| 'line' \| 'polygon' \| 'select' \| 'static'` | `'static'` | Active tool (two-way with [(mode)]). A mode that is not enabled falls back to 'static'. |
| `features` | `FeatureCollection` | `empty` | Drawn features as a GeoJSON FeatureCollection of Point, LineString and Polygon (two-way with [(features)]). Updates when a draw, edit or delete completes. Assigning a collection diffs by feature id; features keep their own ids (any non-empty string or finite number) and those without one get an id; unsupported geometries are dropped and reported through mapError. |
| `editable` | `boolean` | `true` | Enables the select mode: select, drag, reshape and delete features. Changing it restarts terra-draw and drops an unfinished shape. |
| `color` | ``#${string}`` | `theme default` | Accent color of the drawn shapes (#rrggbb). Defaults to a theme-aware blue. Changing it restyles the modes in place (no restart). |

**Outputs**

| Name | Type | Default | Description |
|---|---|---|---|
| `drawEnd` | `MapDrawEvent` | — | Emits { feature, mode, action } when a new shape is completed. |
| `featureEdit` | `MapDrawEvent` | — | Emits { feature, mode, action } when an existing feature is moved, reshaped or otherwise edited. |
| `featureSelect` | `MapDrawFeature` | — | Emits the selected Feature (select mode). |
| `featureDeselect` | `string \| number` | — | Emits the id of the deselected feature. |

## MapContextService

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 reach the raw map.

| Name | Type | Default | Description |
|---|---|---|---|
| `map()` | `Signal<Map \| null>` | — | The raw maplibre-gl Map instance, or null before init. |
| `isLoaded()` | `Signal<boolean>` | — | True when the style is loaded and layers can be added. Gates every source/layer operation; closes during a theme/basemap switch and re-opens once it settles (or fails). |
| `resolvedTheme()` | `Signal<'light' \| 'dark'>` | — | Theme currently applied to the map. |
| `hasSource(id)` | `(id: string) => boolean` | — | Whether a source component (raster, vector, image overlay) currently has a source with this id on the map. Reactive inside effect(); false while a theme switch has removed the style. Wait on it before adding layers that reference source: id. |
| `sourceIds()` | `Signal<ReadonlySet<string>>` | — | Ids of the sources currently announced by source components. |
| `registerSource(id)` | `(id: string) => () => void` | — | Announces a source you added yourself so hasSource(id) sees it; returns the release function to call when you remove it. |
| `fitBounds(options?)` | `(options?: MapFitBoundsOptions) => boolean` | — | Fits the camera to options.bounds, or to the union of the children's data. Returns false when the map is not loaded or there are no bounds. |
| `dataBounds()` | `Signal<[number, number, number, number] \| null>` | — | Union of the bounds registered by the children, as [west, south, east, north]. |
| `registerBounds(getter)` | `(getter: () => LngLatBoundsLike \| null) => () => void` | — | Contributes a bounds source to fit-to-bounds. The getter runs reactively; returns the unregister function (call it on destroy). |

## provideMapStyles()

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.

```ts
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),
  ],
};
```

| Name | Type | Default | Description |
|---|---|---|---|
| `MapStylesConfig` | `{ light?: string \| StyleSpecification; dark?: string \| StyleSpecification }` | — | Per-theme basemap. A theme left undefined falls back to the Carto default for that theme. |
| `provideMapStyles(source)` | `MapStylesConfig \| Signal<MapStylesConfig \| undefined> \| (() => Signal<MapStylesConfig \| undefined>)` | — | Provider for the app-wide basemap. The factory form runs in an injection context, so it can inject() a service holding the signal. |
| `MAP_DEFAULT_STYLES` | `InjectionToken<Signal<MapStylesConfig \| undefined>>` | — | The token itself, if you want to provide it by hand. |

## provideMapLabels()

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.

```ts
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' }" />
```

| Name | Type | Default | Description |
|---|---|---|---|
| `MapLabels` | `{ zoomIn; zoomOut; resetNorth; locate; fullscreen; loading; closePopup; marker: string }` | — | Every user-facing and aria string the library renders. Defaults are English: 'Zoom in', 'Zoom out', 'Reset north', 'My location', 'Toggle fullscreen', 'Loading map', 'Close popup', 'Map marker'. |
| `provideMapLabels(source)` | `Partial<MapLabels> \| Signal<Partial<MapLabels> \| undefined> \| (() => Signal<Partial<MapLabels> \| undefined>)` | — | Provider for app-wide labels; missing keys fall back to the English defaults. The factory form runs in an injection context, so it can inject() a service holding the signal. |
| `MAP_LABELS` | `InjectionToken<Signal<Partial<MapLabels> \| undefined>>` | — | The token itself, if you want to provide it by hand. |
| `DEFAULT_MAP_LABELS` | `MapLabels` | — | The English defaults. |

## Basemaps

Any MapLibre-compatible style works. Set it per map with the `styles` input, or app-wide with `provideMapStyles()`. Precedence: `[styles]` → `[blank]` → `provideMapStyles()` → Carto default.

| Provider | Style URL | API key |
|---|---|---|
| Carto (default) | `https://basemaps.cartocdn.com/gl/{positron|dark-matter|voyager}-gl-style/style.json` | no |
| OpenFreeMap | `https://tiles.openfreemap.org/styles/{liberty|bright|positron|dark|fiord}` | no |
| OpenStreetMap | raster tiles `https://tile.openstreetmap.org/{z}/{x}/{y}.png` — build the StyleSpecification by hand; dev/demo only (tile usage policy) | no |
| MapTiler | `https://api.maptiler.com/maps/{streets-v4|streets-v4-dark|dataviz-v4}/style.json?key=KEY` | yes |
| Stadia Maps | `https://tiles.stadiamaps.com/styles/{alidade_smooth|alidade_smooth_dark}.json?api_key=KEY` | keyless on localhost |

## Theming

Without a `theme` input, the map watches the `dark`/`light` class on `document.documentElement` (works with any theme toggler) and falls back to `prefers-color-scheme`. Switching theme calls `map.setStyle(..., { diff: true })`; every layer component re-adds itself automatically once the style settles.

## SSR

The map is created in `afterNextRender` (browser-only, after hydration) and every child component gates its work on the map signal, which is `null` on the server. On the server the host renders a plain container `<div>` plus the loader, which matches the first client render and hydrates cleanly. Enable `provideClientHydration(withEventReplay())` in the consumer app.

## Invariants (when editing the library sources)

1. Every source/layer operation is gated on `MapContextService.isLoaded()` (map `load` + debounced `styledata`). A theme or basemap switch calls `setStyle`, which destroys layers — the gate closes and reopens, and each layer component's creation `effect` re-adds everything.
2. MapLibre objects are created **once** and reconciled with diffed setters; never destroyed/recreated on input changes.
3. Controlled viewport uses an internal flag around `jumpTo` plus a `map.isMoving()` skip to avoid feedback loops.
4. Teardown is defensive (try/catch): remove layers before the source; symmetric `map.off` for every `map.on(event, layerId, handler)`.
5. Declarative hover = `promoteId` + `setFeatureState` + `mergeHoverPaint` (case expressions on `feature-state hover`).
6. Arcs render an invisible hit layer with `width = max(line-width + 6, 12)` under the visible layer.

## Key Features

- **MapLibre GL JS v6** under the hood — no API keys required (Carto basemaps)
- **Composable** — markers, popups, routes, GeoJSON, arcs, clusters, heatmaps, tile sources, image overlays, 3D buildings and terrain are children of `<ng-map>`
- **Signals-first** — standalone components, `input()`/`output()`, `effect()`-based reconciliation, OnPush
- **Theme-aware** — swaps the basemap at runtime, layers survive the style change
- **SSR-safe** — the map is created in `afterNextRender`; nothing touches `document` on the server
- **Copy-paste distribution** — `ng add ng-mapcn` copies the sources into your project (shadcn-style)

## Tech Stack

- Angular 22+ (standalone, signals, zoneless-friendly)
- TypeScript
- MapLibre GL JS v6
- TailwindCSS (demo site)
- Carto basemaps (default tiles)

## Credits

- [mapcn](https://www.mapcn.dev) — the React + MapLibre GL library this is an Angular port of
- [Zard UI](https://zardui.com) — Angular component library used to build the demo/docs site
- [MapLibre GL JS](https://maplibre.org) — rendering engine
- [Carto](https://carto.com) — default basemaps

## License

MIT