Skip to main content

Clustering

Clustering

Cluster large datasets for better performance and visualization

Tags: cluster aggregation performance large-data

View Demo

Clustering groups nearby points into clusters that display the count of contained points. As users zoom in, clusters expand to reveal individual points. This dramatically improves performance for large datasets and provides better visual clarity.

Import​

<script>
  import { Map, Source, CircleLayer, SymbolLayer } from '@classic-homes/maps-svelte';
</script>
// React
import { Map, Source, CircleLayer, SymbolLayer } from '@classic-homes/maps-react';

Basic Usage​

<script>
  import { Map, Source, CircleLayer, SymbolLayer } from '@classic-homes/maps-svelte';
</script>

<Map title="Clustered Points" center={[-122.4, 37.8]} zoom={10}>
  <Source
    id="points"
    type="geojson"
    data={pointsData}
    cluster
    clusterRadius={50}
    clusterMaxZoom={14}
  />

  <!-- Cluster circles -->
  <CircleLayer
    id="clusters"
    source="points"
    filter={['has', 'point_count']}
    circleColor="#3ba4a7"
    circleRadius={['step', ['get', 'point_count'], 15, 10, 20, 50, 25]}
  />

  <!-- Cluster labels -->
  <SymbolLayer
    id="cluster-count"
    source="points"
    filter={['has', 'point_count']}
    textField={['get', 'point_count_abbreviated']}
    textSize={12}
    textColor="#fff"
  />

  <!-- Unclustered points -->
  <CircleLayer
    id="unclustered"
    source="points"
    filter={['!', ['has', 'point_count']]}
    circleRadius={6}
    circleColor="#ff5722"
  />
</Map>

Props​

Component-Specific Props​

Prop Type Default Description
cluster boolean false Enable clustering on Source
clusterRadius number 50 Cluster radius in pixels
clusterMaxZoom number 14 Max zoom for clustering
clusterMinPoints number 2 Min points to form cluster

Inherited Base Map Props​

Prop Type Default Description
title string required Map title for accessibility (aria-label)
description string - Optional description for screen readers
height number | string 400 Map height in pixels or CSS value
width number | string - Map width in pixels or CSS value
loading boolean false Show loading skeleton
error string | null - Error message to display
emptyMessage string - Message shown when data is empty
theme 'light' | 'dark' | 'auto' 'auto' Theme preference
animation boolean true Enable/disable animations (respects prefers-reduced-motion)
class string - Custom CSS class for styling

Accessibility​

  • The title prop is used as aria-label for screen readers
  • Keyboard navigation support for interactive elements
  • Animations respect prefers-reduced-motion media query
  • High contrast colors in both light and dark modes
On this page