mapboxFocusSingleFeature

Overview

mapboxFocusSingleFeature() is a utility function that helps focus the map view on a specific GeoJSON feature. It intelligently handles both clustered and non-clustered features, automatically calculating the appropriate zoom level needed to break clustered features out of their clusters.

Behavior for unclustered features:
When the feature isn't clustered, simply fly to it.

1. Uses map.flyTo() to center the map on the feature's coordinates

Behavior for clustered features:
When the feature is clustered, zoom to the minimum expansion zoom needed to break this feature out of the cluster.

1. Gets all current clusters in the visible map area (using -180 to 180 longitude, -85 to 85 latitude)
2. Filters to only keep clustered features
3. Calculates the minimum zoom level needed to break this feature out of its cluster
4. Sets a minimum zoom level of 10 (won't zoom out further than this)
5. Flies to the feature's location at the calculated zoom level

Usage

import { mapboxFocusSingleFeature } from '~/utils/mapboxFocusSingleFeature';

// Focus on a non-clustered feature
mapboxFocusSingleFeature(map, supercluster, feature);

// Focus on a clustered feature with custom animation options
mapboxFocusSingleFeature(map, supercluster, feature, {
    duration: 1000,
    easing: (t) => t * (2 - t)
});

API Reference

mapboxFocusSingleFeature()

Focuses the map view on a single feature, handling both clustered and non-clustered features.

Type Definitions

/**
 * Focuses the map view on a single feature, handling both clustered and non-clustered features.
 * For non-clustered features, it simply flies to the feature's location.
 * For clustered features, it calculates the minimum zoom level needed to break the feature out of its cluster.
 *
 * @param map - The Mapbox GL map instance. If null, the function will return early.
 * @param supercluster - The Supercluster instance used for managing the clusters.
 * @param feature - The GeoJSON feature to focus on. Can be either a clustered or non-clustered feature.
 * @param options - Optional easing options for the map animation.
 */
export function mapboxFocusSingleFeature(
    map: Map | null,
    supercluster: Supercluster,
    feature: Feature<Point, { cluster?: boolean }>,
    options?: EasingOptions,
): void;

Example

const map = new mapboxgl.Map({ ... });
const supercluster = new Supercluster({ ... });

// Non-clustered feature
const pointFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [0, 0]
    },
    properties: {}
};

// Clustered feature
const clusteredFeature = {
    type: 'Feature',
    geometry: {
        type: 'Point',
        coordinates: [0, 0]
    },
    properties: {
        cluster: true
    }
};

// Focus on non-clustered feature
mapboxFocusSingleFeature(map, supercluster, pointFeature);

// Focus on clustered feature with custom animation
mapboxFocusSingleFeature(map, supercluster, clusteredFeature, {
    duration: 1000,
    easing: (t) => t * (2 - t)
});

Notes

• The function will return early if the map instance is null
• For clustered features, the minimum zoom level is capped at 10
• The function uses the entire world bounds (-180, -85, 180, 85) to find clusters
• The current map zoom level is used as a starting point for cluster calculations

Changelog