Camera

Controls the perspective from which the user sees the map. The Camera component manages the map’s center coordinate, zoom level, bearing, and pitch.

Import

import { Camera } from '@rnmapbox/maps';

Basic Usage

import { MapView, Camera } from '@rnmapbox/maps';

function MyMap() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
        pitch={45}
        heading={0}
      />
    </MapView>
  );
}

Imperative Methods

To use imperative methods, pass in a ref object:

import { useRef, useEffect } from 'react';
import { MapView, Camera } from '@rnmapbox/maps';

function MyMap() {
  const cameraRef = useRef<Camera>(null);

  useEffect(() => {
    cameraRef.current?.setCamera({
      centerCoordinate: [-74.006, 40.7128],
      zoomLevel: 14,
      animationDuration: 2000,
    });
  }, []);

  return (
    <MapView style={{ flex: 1 }}>
      <Camera ref={cameraRef} />
    </MapView>
  );
}

Props

centerCoordinate

[longitude: number, latitude: number]

The location on which the map should center.

<Camera centerCoordinate={[-122.4194, 37.7749]} />

bounds

{ ne: Position, sw: Position, paddingTop?: number, paddingRight?: number, paddingBottom?: number, paddingLeft?: number }

The corners of a box around which the map should bound. Contains padding props for backwards compatibility; the root padding prop should be used instead.

<Camera
  bounds={{
    ne: [-122.4, 37.8],
    sw: [-122.5, 37.7],
  }}
/>

heading

number

The heading (orientation) of the map in degrees, where 0° is north.

<Camera heading={90} /> {/* East */}

pitch

number

The pitch (tilt) of the map in degrees, where 0° is looking straight down.

<Camera pitch={45} />

zoomLevel

number

The zoom level of the map. Higher values zoom in closer.

<Camera zoomLevel={14} />

padding

{ paddingLeft: number, paddingRight: number, paddingTop: number, paddingBottom: number }

The viewport padding in points.

<Camera
  padding={{
    paddingTop: 50,
    paddingBottom: 50,
    paddingLeft: 20,
    paddingRight: 20,
  }}
/>

animationDuration

number

The duration the map takes to animate to a new configuration, in milliseconds.

<Camera
  centerCoordinate={[-122.4194, 37.7749]}
  animationDuration={2000}
/>

animationMode

'flyTo' | 'easeTo' | 'linearTo' | 'moveTo' | 'none'

The easing or path the camera uses to animate to a new configuration.

flyTo - Smooth, realistic “flying” animation
easeTo - Smooth easing animation
linearTo - Linear animation
moveTo - Instant movement
none - No animation

<Camera
  centerCoordinate={[-122.4194, 37.7749]}
  animationMode="flyTo"
  animationDuration={3000}
/>

followUserLocation

boolean

Whether the map orientation follows the user location.

<Camera followUserLocation={true} followZoomLevel={16} />

followUserMode

UserTrackingMode

The mode used to track the user location on the map.

UserTrackingMode.Follow - Follow user location
UserTrackingMode.FollowWithHeading - Follow with compass heading
UserTrackingMode.FollowWithCourse - Follow with course direction

import { Camera, UserTrackingMode } from '@rnmapbox/maps';

<Camera
  followUserLocation={true}
  followUserMode={UserTrackingMode.FollowWithHeading}
/>

followZoomLevel

number

The zoom level used when following the user location.

<Camera followUserLocation={true} followZoomLevel={16} />

followPitch

number

The pitch used when following the user location.

<Camera followUserLocation={true} followPitch={45} />

followHeading

number

The heading used when following the user location.

followPadding

Partial<{ paddingLeft: number, paddingRight: number, paddingTop: number, paddingBottom: number }>

The padding used to position the user location when following.

<Camera
  followUserLocation={true}
  followPadding={{ paddingBottom: 200 }}
/>

minZoomLevel

number

The lowest allowed zoom level.

<Camera minZoomLevel={5} maxZoomLevel={18} />

maxZoomLevel

number

The highest allowed zoom level.

<Camera minZoomLevel={5} maxZoomLevel={18} />

maxBounds

{ ne: Position, sw: Position }

The corners of a box defining the limits of where the camera can pan or zoom.

<Camera
  maxBounds={{
    ne: [-122.0, 38.0],
    sw: [-123.0, 37.0],
  }}
/>

defaultSettings

CameraStop

The configuration that the camera falls back on if no other values are specified.

<Camera
  defaultSettings={{
    centerCoordinate: [-122.4194, 37.7749],
    zoomLevel: 12,
  }}
/>

allowUpdates

boolean

default:"true"

Whether the camera should send any configuration to the native module. Prevents unnecessary tile fetching and improves performance when the map is not visible.

<Camera allowUpdates={isMapVisible} />

triggerKey

string | number

Any arbitrary primitive value that, when changed, causes the camera to retry moving to its target configuration. (Not yet implemented.)

onUserTrackingModeChange

(event: MapboxGLEvent) => void

Deprecated: Use Viewport#onStatusChanged instead.

Executes when user tracking mode changes.

Methods

setCamera()

setCamera(config: CameraStop | CameraStops): void

Sets any camera properties, with default fallbacks if unspecified.

cameraRef.current?.setCamera({
  centerCoordinate: [-122.4194, 37.7749],
  zoomLevel: 14,
  pitch: 45,
  animationDuration: 2000,
  animationMode: 'flyTo',
});

CameraStop Properties:

centerCoordinate?: [number, number]
bounds?: { ne: Position, sw: Position }
heading?: number
pitch?: number
zoomLevel?: number
padding?: CameraPadding
animationDuration?: number
animationMode?: CameraAnimationMode

fitBounds()

fitBounds(
  ne: Position,
  sw: Position,
  paddingConfig?: number | number[],
  animationDuration?: number
): void

Set the camera position to enclose the provided bounds, with optional padding and duration.

// Simple bounds
cameraRef.current?.fitBounds(
  [-122.4, 37.8],  // northeast
  [-122.5, 37.7],  // southwest
);

// With padding and animation
cameraRef.current?.fitBounds(
  [-122.4, 37.8],
  [-122.5, 37.7],
  [20, 40],  // [vertical, horizontal] padding
  1000       // 1 second animation
);

// With all-side padding
cameraRef.current?.fitBounds(
  [-122.4, 37.8],
  [-122.5, 37.7],
  [20, 40, 20, 40],  // [top, right, bottom, left]
  1000
);

flyTo()

flyTo(
  centerCoordinate: Position,
  animationDuration?: number
): void

Sets the camera to center around the provided coordinate using a realistic “travel” animation.

cameraRef.current?.flyTo([-122.4194, 37.7749]);
cameraRef.current?.flyTo([-122.4194, 37.7749], 3000);

moveTo()

moveTo(
  centerCoordinate: Position,
  animationDuration?: number
): void

Sets the camera to center around the provided coordinate, with optional duration.

cameraRef.current?.moveTo([-122.4194, 37.7749]);
cameraRef.current?.moveTo([-122.4194, 37.7749], 500);

zoomTo()

zoomTo(
  zoomLevel: number,
  animationDuration?: number
): void

Zooms the camera to the provided level, with optional duration.

cameraRef.current?.zoomTo(16);
cameraRef.current?.zoomTo(16, 1000);

moveBy()

moveBy(props: {
  x: number;
  y: number;
  animationMode?: 'easeTo' | 'linearTo';
  animationDuration?: number;
}): void

Move the map by a given screen coordinate offset with optional animation. Useful for Android Auto or CarPlay pan gestures.

cameraRef.current?.moveBy({ x: 100, y: 50 });

cameraRef.current?.moveBy({
  x: 100,
  y: 50,
  animationMode: 'easeTo',
  animationDuration: 500,
});

scaleBy()

scaleBy(props: {
  x: number;
  y: number;
  scaleFactor: number;
  animationMode?: 'easeTo' | 'linearTo';
  animationDuration?: number;
}): void

Scale the map with optional animation. Useful for Android Auto pinch gestures or double tap.

cameraRef.current?.scaleBy({
  x: 200,
  y: 200,
  scaleFactor: 2.0,  // zoom in
});

cameraRef.current?.scaleBy({
  x: 200,
  y: 200,
  scaleFactor: 0.5,  // zoom out
  animationMode: 'easeTo',
  animationDuration: 300,
});

Examples

Basic Camera
Animated Camera
Fit Bounds
Follow User Location
Imperative Control

import { MapView, Camera } from '@rnmapbox/maps';

function BasicCamera() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
        pitch={45}
        heading={90}
      />
    </MapView>
  );
}

import { MapView, Camera } from '@rnmapbox/maps';

function AnimatedCamera() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        centerCoordinate={[-74.006, 40.7128]}
        zoomLevel={14}
        animationMode="flyTo"
        animationDuration={3000}
      />
    </MapView>
  );
}

import { MapView, Camera } from '@rnmapbox/maps';

function FitBoundsCamera() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        bounds={{
          ne: [-122.4, 37.8],
          sw: [-122.5, 37.7],
        }}
        padding={{
          paddingTop: 50,
          paddingBottom: 50,
          paddingLeft: 20,
          paddingRight: 20,
        }}
        animationDuration={1000}
      />
    </MapView>
  );
}

import { MapView, Camera, UserTrackingMode } from '@rnmapbox/maps';

function FollowUserCamera() {
  return (
    <MapView style={{ flex: 1 }}>
      <Camera
        followUserLocation={true}
        followUserMode={UserTrackingMode.FollowWithHeading}
        followZoomLevel={16}
        followPitch={45}
      />
    </MapView>
  );
}

import { useRef } from 'react';
import { MapView, Camera } from '@rnmapbox/maps';
import { Button, View } from 'react-native';

function ImperativeCamera() {
  const cameraRef = useRef<Camera>(null);

  const flyToNewYork = () => {
    cameraRef.current?.flyTo([-74.006, 40.7128], 2000);
  };

  const flyToSanFrancisco = () => {
    cameraRef.current?.flyTo([-122.4194, 37.7749], 2000);
  };

  const zoomIn = () => {
    cameraRef.current?.zoomTo(16, 500);
  };

  return (
    <>
      <MapView style={{ flex: 1 }}>
        <Camera ref={cameraRef} />
      </MapView>
      <View style={{ position: 'absolute', bottom: 20, left: 20 }}>
        <Button title="Fly to NYC" onPress={flyToNewYork} />
        <Button title="Fly to SF" onPress={flyToSanFrancisco} />
        <Button title="Zoom In" onPress={zoomIn} />
      </View>
    </>
  );
}

MapView - The map container
UserLocation - Show user location
Viewport - Advanced camera control

Core Components

Sources

Layers

Annotations

Location

Assets

Terrain

Offline & Utilities

Modules

Documentation Index

​Camera

​Import

​Basic Usage

​Imperative Methods

​Props

​centerCoordinate

​bounds

​heading

​pitch

​zoomLevel

​padding

​animationDuration

​animationMode

​followUserLocation

​followUserMode

​followZoomLevel

​followPitch

​followHeading

​followPadding

​minZoomLevel

​maxZoomLevel

​maxBounds

​defaultSettings

​allowUpdates

​triggerKey

​onUserTrackingModeChange

​Methods

​setCamera()

​fitBounds()

​flyTo()

​moveTo()

​zoomTo()

​moveBy()

​scaleBy()

​Examples

​Related Components

Build docs developers (and LLMs) love

Camera

Import

Basic Usage

Imperative Methods

Props

centerCoordinate

bounds

heading

pitch

zoomLevel

padding

animationDuration

animationMode

followUserLocation

followUserMode

followZoomLevel

followPitch

followHeading

followPadding

minZoomLevel

maxZoomLevel

maxBounds

defaultSettings

allowUpdates

triggerKey

onUserTrackingModeChange

Methods

setCamera()

fitBounds()

flyTo()

moveTo()

zoomTo()

moveBy()

scaleBy()

Examples

Related Components