Clustering

Live clustering isn't available yet — the clustering addon hasn't been ported to the v2 API. See issue #22. The code on this page shows the intended shape of the API, not something you can install today.

Drawing a lot of markers close together turns into a usability nightmare fast. Grouping — clustering — markers is the standard way to keep things readable when you're showing large numbers of them.

Clustering support will come from a separate addon, installed alongside ember-google-maps:

# Not published yet — tracked in issue #22.
ember install ember-google-maps-clustering

It'll wrap @googlemaps/markerclusterer, Google's own clustering library, and add a MarkerClusterer component to the map. Like any map component, it'll take clustering options directly as arguments.

TIP

MarkerClusterer will yield its own marker component, meant to be added to the cluster instead of straight to the map. Don't mix it up with the regular Marker yielded by the map itself.

WARNING

The snippet below is illustrative pseudocode showing the planned API. The ember-google-maps-clustering package is not yet published or runnable.

import Component from '@glimmer/component';
import { GMap } from 'ember-google-maps';
import { MarkerClusterer, ClusterMarker } from 'ember-google-maps-clustering';

export default class ClusteringExample extends Component {
  locations = [
    { id: '1', lat: 51.508, lng: -0.128 },
    { id: '2', lat: 51.503, lng: -0.12 },
    { id: '3', lat: 51.515, lng: -0.141 },
  ];

  <template>
    <GMap @lat={{51.507568}} @lng={{-0.127762}} @zoom={{12}}>
      <MarkerClusterer as |cluster|>
        {{#each this.locations key="id" as |location|}}
          <ClusterMarker
            @lat={{location.lat}}
            @lng={{location.lng}}
            @cluster={{cluster}}
          />
        {{/each}}
      </MarkerClusterer>
    </GMap>
  </template>
}

Default cluster icons

The clustering library ships with a small set of default cluster icons. Expect these to be configurable, mirroring the underlying library — exact option names will land with the port (issue #22).

Cluster events

You'll be able to register events the same way as on any other component — the usual suspects like @onClick and @onDblclick, plus two clustering-specific events: @onClusteringbegin and @onClusteringend. Keep in mind these can fire more than once during a single render, since clustering happens in batches.

<MarkerClusterer
  @onClusteringbegin={{this.onClusteringBegin}}
  @onClusteringend={{this.onClusteringEnd}}
  as |cluster|
>
  {{! ... }}
</MarkerClusterer>