mapboxFindExpansionZoomForFeature

Overview

mapboxFindExpansionZoomForFeature() is a utility function that helps determine the exact zoom level at which a specific feature will become visible as an individual point rather than being part of a cluster. This is particularly useful when you want to smoothly zoom to a specific feature that might be contained within a cluster.

Behavior for unclustered features:
The function works by recursively traversing the cluster hierarchy:

First checks if the feature is already visible at the current zoom level

If not, finds the cluster containing the feature

Gets the expansion zoom for that cluster

Recursively checks if the feature is visible at that zoom level

Continues until either:

The feature is found at the current level
No containing cluster is found
The maximum zoom level is reached

Usage

import { mapboxFindExpansionZoomForFeature } from '~/utils/mapboxFindExpansionZoomForFeature';
import type { Feature, Point } from "geojson";
import Supercluster from "supercluster";

const supercluster = new Supercluster({ ... });
const features = [
  { type: 'Feature', id: 'cluster1', properties: { cluster: true } },
  { type: 'Feature', id: 'point1', properties: { cluster: false } }
];

const zoom = mapboxFindExpansionZoomForFeature(supercluster, features, 'point1', 10);

API Reference

Finds the minimum zoom level needed to break a feature out of its cluster.

Prop	Default	Type
`index`*		`Supercluster` The Supercluster instance containing the feature and cluster data
`features`*		`Array<Feature<Point, { cluster?: boolean }>>` Array of GeoJSON features to search through, typically containing clusters
`id`*		`string \| number \| undefined` The ID of the feature to find the expansion zoom for
`currentZoom`*		`number` The current zoom level of the map

Method	Type
`returns`	`number` The minimum zoom level needed to break the feature out of its cluster, or currentZoom if not found

Type Definitions

/**
 * Recursively finds the minimum zoom level needed to break a feature out of its cluster.
 * This function traverses the cluster hierarchy to determine the exact zoom level where
 * the feature will become visible as an individual point rather than part of a cluster.
 *
 * @param index - The Supercluster instance containing the feature and cluster data.
 * @param features - Array of GeoJSON features to search through, typically containing clusters.
 * @param id - The ID of the feature to find the expansion zoom for. If undefined or not found, returns currentZoom.
 * @param currentZoom - The current zoom level of the map.
 * @returns The minimum zoom level needed to break the feature out of its cluster, or currentZoom if not found.
 */
export function mapboxFindExpansionZoomForFeature(
    index: Supercluster,
    features: Array<Feature<Point, { cluster?: boolean }>>,
    id: string | number | undefined,
    currentZoom: number,
): number;

Example

<script setup lang="ts">
import { injectMapboxMapContext } from './MapboxMap.vue';
import { mapboxFindExpansionZoomForFeature } from '~/utils/mapboxFindExpansionZoomForFeature';

const { map } = injectMapboxMapContext();

function zoomToFeature(featureId: string) {
  if (!map.value) return;
  
  const currentZoom = map.value.getZoom();
  const zoom = mapboxFindExpansionZoomForFeature(
    supercluster,
    features,
    featureId,
    currentZoom
  );
  
  map.value.easeTo({
    zoom,
    duration: 1000
  });
}
</script>

v0.1.0

on April 25, 2025

#5aa3607d

improvement: added missing utils that where already used in projects