# ng-mapcn

> 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 · npm: https://www.npmjs.com/package/ng-mapcn

## Overview

- [Home](https://ng-mapcn.vercel.app/): live examples — trails, arcs, fly-to, delivery, analytics, EV charging.
- [Documentation](https://ng-mapcn.vercel.app/docs): introduction, features and supported basemaps.
- [Installation](https://ng-mapcn.vercel.app/docs/installation): `ng add` (copy-paste) or npm package.
- [Map Styles](https://ng-mapcn.vercel.app/docs/basemaps): a working example per provider (Carto, OpenFreeMap, OpenStreetMap, MapTiler, Stadia).
- [API Reference](https://ng-mapcn.vercel.app/docs/api-reference): every component with inputs and outputs.
- [Credits](https://ng-mapcn.vercel.app/credits): mapcn, Zard UI, MapLibre, Carto.
- [Repository](https://github.com/juanvieiraprado99/ng-mapcn): source, issues, releases.
- [llms-full.txt](https://ng-mapcn.vercel.app/llms-full.txt): the complete API in one file, for agents.

## Components

Docs pages: [Map](https://ng-mapcn.vercel.app/docs/components/map) · [Controls](https://ng-mapcn.vercel.app/docs/components/controls) · [Markers](https://ng-mapcn.vercel.app/docs/components/markers) · [Popups](https://ng-mapcn.vercel.app/docs/components/popups) · [Routes](https://ng-mapcn.vercel.app/docs/components/routes) · [Arcs](https://ng-mapcn.vercel.app/docs/components/arcs) · [GeoJSON](https://ng-mapcn.vercel.app/docs/components/geojson) · [Clusters](https://ng-mapcn.vercel.app/docs/components/clusters) · [Heatmap](https://ng-mapcn.vercel.app/docs/components/heatmap) · [Tile Sources](https://ng-mapcn.vercel.app/docs/components/tile-sources) · [3D Buildings & Terrain](https://ng-mapcn.vercel.app/docs/components/3d) · [Draw](https://ng-mapcn.vercel.app/docs/components/draw) · [Advanced](https://ng-mapcn.vercel.app/docs/components/advanced)

- **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.
- **MapControls** (`ng-map-controls`): Renders map control buttons: zoom, compass, locate, and fullscreen. Must be used inside ng-map.
- **MapMarker** (`ng-map-marker`): A container for marker-related components. Provides context for its children and handles marker positioning.
- **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.
- **MarkerLabel** (`ng-marker-label`): An always-visible text label above or below the marker. Must be used inside ng-marker-content.
- **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).
- **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.
- **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).
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **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.
- **MapImageOverlay** (`ng-map-image-overlay`): Georeferenced image pinned to four corner coordinates, drawn as a raster layer. Must be used inside ng-map.
- **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.
- **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.
- **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.

`ng-map` also takes `[fitBounds]="{ padding, maxZoom, duration, animate, bounds? }"` to fit the camera to its children's data (or explicit `bounds`) once loaded and whenever they change; `MapContextService.fitBounds()` is the imperative form.

Utilities: `MapViewport`, `getViewport`, `buildArcCoordinates`, `mergeHoverPaint`, `blankMapStyle`, `defaultStyles`, `MapStylesConfig`, `provideMapStyles()`, `MAP_DEFAULT_STYLES`, and `MapContextService` (map / isLoaded / resolvedTheme signals and the `hasSource(id)` source registry, the equivalent of mapcn's `useMap()`).

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

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

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