Clusters

Cluster large point datasets with zoom-to-expand behavior.

Basic Example

#

ng-map-cluster-layer clusters point features automatically. Circle color and size scale with the cluster count; clicking a cluster zooms in, clicking a point emits pointClick. This example shows USGS earthquake data. 

import { Component } from '@angular/core';
import { MapClusterLayerComponent, MapComponent } from 'ng-mapcn';

@Component({
  selector: 'app-cluster-map',
  standalone: true,
  imports: [MapComponent, MapClusterLayerComponent],
  template: `
    <div class="h-[420px]">
      <ng-map [center]="[-103.5917, 40.6699]" [zoom]="3">
        <ng-map-cluster-layer
          [data]="earthquakesUrl"
          [clusterMaxZoom]="14"
          [clusterRadius]="50"
          (pointClick)="onPoint($event)"
        />
      </ng-map>
    </div>
  `,
})
export class ClusterMapComponent {
  // USGS earthquake data (GeoJSON points)
  readonly earthquakesUrl =
    'https://maplibre.org/maplibre-gl-js/docs/assets/earthquakes.geojson';

  onPoint(event: ClusterPointClickEvent): void {
    console.log(event.feature.properties);
  }
}

Ids and z-order

#

Set id to get stable source and layer ids you can target with queryRenderedFeatures or custom layers, and beforeId to insert the cluster layers below an existing layer. Both follow ng-map-geojson: beforeId is applied when the layers are created, and changing id re-creates them. 

<ng-map-cluster-layer id="stores" beforeId="labels" [data]="stores" />

// Layer ids derived from id="stores":
//   source:               cluster-source-stores
//   cluster circles:      clusters-stores
//   cluster count labels: cluster-count-stores
//   unclustered points:   unclustered-point-stores
// Without id they are auto-generated (e.g. clusters-ng-cluster-1).

Typed properties

#

ng-map-cluster-layer and ng-map-geojson are generic over the feature properties. The type is inferred from [data], so click and hover payloads are typed. It defaults to Record<string, unknown>. 

interface Store {
  name: string;
  open: boolean;
}

readonly stores: GeoJSON.FeatureCollection<GeoJSON.Point, Store> = { /* ... */ };

// P is inferred from [data]: event.feature.properties is typed as Store
onPoint(event: ClusterPointClickEvent<Store>): void {
  console.log(event.feature.properties.name);
}

Default colors

#

ng-mapcn clusters default to green, yellow and red (#22c55e, #eab308, #ef4444), while mapcn uses blues (#3b82f6, #1d4ed8, #1e3a8a). Pass clusterColors to match mapcn. 

<!-- ng-mapcn defaults: ['#22c55e', '#eab308', '#ef4444'] (green/yellow/red) -->
<!-- mapcn defaults, for an identical look: -->
<ng-map-cluster-layer
  [data]="stores"
  [clusterColors]="['#3b82f6', '#1d4ed8', '#1e3a8a']"
/>
GeoJSON Heatmap