MapboxCluster

Display a cluster on the map with data coming from a GeoJSON source.

• Mapbox cluster example
• Layer Style Specification

Table of contents

• Examples
• Props
• Events

Examples

Basic usage

<script setup>
  import { MapboxMap, MapboxCluster } from '@studiometa/vue-mapbox-gl';
</script>

<template>
  <MapboxMap
    style="height: 400px"
    access-token="..."
    map-style="mapbox://styles/mapbox/streets-v11">
    <MapboxCluster data="/earthquakes.json" />
  </MapboxMap>
</template>

Open popup on feature click

<script setup>
  import { ref, nextTick } from 'vue';
  import { MapboxMap, MapboxPopup, MapboxCluster } from '@studiometa/vue-mapbox-gl';

  const mapCenter = ref([0, 0]);
  const isOpen = ref(false);
  const position = ref([0, 0]);
  const content = ref();

  async function openPopup({ geometry, properties }) {
    await nextTick();
    position.value = [...geometry.coordinates];
    isOpen.value = true;

    /**
     * Mapbox GL convert's properties values to JSON, so we need to parse them
     * to retreive any complex data structure such as arrays and objects.
     */
    content.value = Object.fromEntries(
      Object.entries(properties).map(([key, value]) => {
        try {
          return [key, JSON.parse(value)];
        } catch (err) {
          // Silence is golden.
        }

        return [key, value];
      })
    );
  }
</script>

<template>
  <MapboxMap
    :access-token="MAPBOX_API_KEY"
    map-style="mapbox://styles/mapbox/streets-v11"
    :center="mapCenter"
    :zoom="1">
    <MapboxPopup
      v-if="isOpen"
      :key="position.join('-')"
      :lng-lat="position"
      anchor="bottom"
      @mb-close="() => (isOpen = false)">
      <pre>{{ content }}</pre>
    </MapboxPopup>
    <MapboxCluster data="/earthquakes.json" @mb-feature-click="openPopup" />
  </MapboxMap>
</template>

WARNING

The :center prop of the MapboxMap component must be set via a data property (see mapCenter in the example above) instead of directly in the template, as it can create unexpected behaviours when clicking on a cluster feature.

Custom marker for unclustured points

<script setup>
  import { ref } from "vue";
  import { MapboxMap, MapboxImage, MapboxCluster } from '@studiometa/vue-mapbox-gl';

  const mapCenter = ref([0, 0]);
</script>

<template>
  <MapboxMap
    style="height: 400px"
    :access-token="MAPBOX_API_KEY"
    map-style="mapbox://styles/mapbox/streets-v11"
    :center="mapCenter"
    :zoom="1">
    <MapboxImage
      id="cat"
      src="https://upload.wikimedia.org/wikipedia/commons/thumb/6/60/Cat_silhouette.svg/400px-Cat_silhouette.svg.png">
      <MapboxCluster
        data="/earthquakes.json"
        unclustered-point-layer-type="symbol"
        :unclustered-point-layout="{
          'icon-image': 'cat',
          'icon-size': 0.1,
        }"
        :unclustered-point-paint="null" />
    </MapboxImage>
  </MapboxMap>
</template>

Props

data

• Type [ String, Object ]
• Required true

The source of the data for the clustered points, must be a String or an Object of GeoJSON format.

clusterMaxZoom

• Type Number
• Default 14

The max zoom to cluster points on.

clusterRadius

• Type Number
• Default 50

Radius of each cluster when clustering point.

clusterMinPoints

• Type Number
• Default 2

Minimum number of points necessary to form a cluster.

clusterProperties

• Type Object
• Default {}}

An object defining custom properties on the generated clusters.

clustersLayout

• Type Object
• Default {}

The layout configuration for the clusters circles layer.

clustersPaint

• Type Object
• Default { 'circle-color': '#000', 'circle-radius': 40 }

The paint configuration for the clusters circles layer.

clusterCountLayout

• Type Object
• Default { 'text-field': [ 'get', 'point_count_abbreviated' ] }

The layout configuration for the clusters count layer.

clusterCountPaint

• Type Object
• Default { 'text-color': 'white' }

The paint configuration for the clusters count layer.

unclusteredPointLayerType

• Type String
• Default 'circle'

The type of the unclustered points layer.

unclusteredPointLayout

• Type Object
• Default {}

The layout configuration for the unclustered points layer.

unclusteredPointPaint

• Type Object
• Default { 'circle-color': '#000', 'circle-radius': 4 }

The paint configuration for the unclustered points layer.

Events

mb-cluster-click

Emitted when the user clicks on a cluster.

Params

• clusterId: the ID of the cluster being clicked
• event: the Mapbox event object sent by the layer

mb-feature-click

Emitted when the user clicks on a unclustered point (a feature).

Params

• feature: the feature being clicked on
• event: the Mapbox event object sent by the layer

mb-feature-mouseenter

Emitted when the user's mouse enters an unclustered point.

Params

• feature: the feature being clicked on
• event: the Mapbox event object sent by the layer

mb-feature-mouseleave

Emitted when the user's mouse leaves an unclustered point.

Params

• event: the Mapbox event object sent by the layer