[Bug]: dense onCameraChanged traffic during gestures can overwhelm JS without a native throttle

[ciospettw]

Mapbox Version

11.20.1

React Native Version

0.83.2

Platform

• iOS
• Android

@rnmapbox/maps version

10.3.0

Standalone component to reproduce

import React, { useMemo, useState } from 'react';
import { Camera, CircleLayer, MapView, ShapeSource } from '@rnmapbox/maps';

function buildPoints(count) {
  return {
    type: 'FeatureCollection',
    features: Array.from({ length: count }, (_, index) => {
      const row = Math.floor(index / 100);
      const column = index % 100;
      return {
        type: 'Feature',
        geometry: {
          type: 'Point',
          coordinates: [12.2 + column * 0.01, 41.6 + row * 0.01],
        },
        properties: { id: String(index) },
      };
    }),
  };
}

export default function BugReportExample() {
  const [cameraChangedCount, setCameraChangedCount] = useState(0);
  const [mapIdleCount, setMapIdleCount] = useState(0);
  const shape = useMemo(() => buildPoints(5000), []);

  return (
    <MapView
      style={{ flex: 1 }}
      onCameraChanged={() => {
        setCameraChangedCount((count) => count + 1);
      }}
      onMapIdle={() => {
        setMapIdleCount((count) => count + 1);
      }}
    >
      <Camera centerCoordinate={[12.4964, 41.9028]} zoomLevel={7} />
      <ShapeSource id="dense-points" shape={shape}>
        <CircleLayer
          id="dense-point-layer"
          style={{
            circleRadius: 3,
            circleColor: '#ff4d4d',
          }}
        />
      </ShapeSource>
    </MapView>
  );
}

Observed behavior and steps to reproduce

1. Render a map with a dense source and attach non-trivial JS work to onCameraChanged.
2. Pinch-zoom repeatedly.
3. onCameraChanged fires on every native camera tick on both platforms.
4. Even if the heavy work is app-side, there is currently no native throttle for this event, so gesture-driven zoom can overwhelm the JS thread faster than onMapIdle can settle.

In practice this shows up as zoom stutter in apps that recompute visible data, declutter symbols, or trigger viewport-based fetches during camera changes.

Expected behavior

There should be an opt-in way to reduce onCameraChanged event volume natively while keeping the default behavior unchanged for existing consumers.

A cameraChangedThrottleInterval prop on MapView would let apps trade off intermediate camera granularity against JS load, while still using onMapIdle for the final settled camera state.

Notes / preliminary analysis

• This is not a request to change the default event semantics.
• The change is backward compatible if the prop defaults to 0 and preserves current behavior when omitted.
• The API shape is consistent with the existing debounce/timing-related MapView props.
• A small patch that adds cameraChangedThrottleInterval?: number on the JS side and throttles native cameraChanged dispatch on Android and iOS appears sufficient.

Additional links and references

• A PR with an opt-in implementation and example update will be linked from this issue.

[ciospettw]

A proposed fix is available in #4193: #4193

[mfazekas]

@ciospettw Thanks! I don't see in your issue description why throttling on the JS side wouldn't work here. The callback itself is cheap — the overhead is whatever work you're doing inside it. You can just wrap your handler with throttle or debounce from lodash and control the rate yourself:

onCameraChanged={throttle(() => {
  // your expensive work here
}, 100)}

Even at 120fps we have ~8ms per frame, so running a debounce check on every tick is negligible. Adding a native throttle mechanism adds complexity and a new prop to maintain, while the same effect is already achievable in userland. Have you tried this approach?

[ciospettw]

@ciospettw Thanks! I don't see in your issue description why throttling on the JS side wouldn't work here. The callback itself is cheap — the overhead is whatever work you're doing inside it. You can just wrap your handler with throttle or debounce from lodash and control the rate yourself:

onCameraChanged={throttle(() => {
// your expensive work here
}, 100)}
Even at 120fps we have ~8ms per frame, so running a debounce check on every tick is negligible. Adding a native throttle mechanism adds complexity and a new prop to maintain, while the same effect is already achievable in userland. Have you tried this approach?

Thanks, that’s a fair question - The motivation here is not only the work done inside the JS callback. In this case the cost also includes the native-side event frequency and the bridge/event dispatch of onCameraChanged itself during pinch-zoom.

I agree that throttling the JS handler can reduce app-side work, and that’s useful. But it does not reduce the amount of camera-changed events produced natively before they reach JS.

In my app the improvement came from combining:

• moving heavier recomputation to onMapIdle
• keeping onCameraChanged lightweight
• adding this opt-in native throttle for intermediate camera-changed events

With the modified build I’m seeing noticeably less zoom lag on dense marker datasets. The proposal also keeps current behavior unchanged by default (cameraChangedThrottleInterval = 0 unless explicitly set).- For my use case I'm already using a patched build and it performs noticeably better, so if upstream wants to integrate it I'm happy to help, and if not I'm fine keeping it app-specific. Thank You.