snapshotManager
The snapshotManager generates static raster images of the map. Each snapshot image depicts a portion of a map defined by a SnapshotOptions object. The snapshotter generates snapshots asynchronously.
Import
import { snapshotManager } from '@rnmapbox/maps';
Basic Usage
import { snapshotManager } from '@rnmapbox/maps';
const uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.126410, 40.797968],
width: 300,
height: 200,
zoomLevel: 12,
styleURL: 'mapbox://styles/mapbox/streets-v11',
});
console.log('Snapshot URI:', uri);
Methods
takeSnap()
takeSnap(options: SnapshotOptions): Promise<string>
The pitch, heading, and zoomLevel options only work when centerCoordinate is set!
Configuration for the snapshot.The center coordinate of the snapshot [longitude, latitude]. Either centerCoordinate or bounds must be provided.
options.bounds
[[number, number], [number, number]]
Geographic bounds for the snapshot [[lng1, lat1], [lng2, lat2]]. Either centerCoordinate or bounds must be provided.
Width of the snapshot in points/pixels.
Height of the snapshot in points/pixels.
Zoom level for the snapshot. Only works with centerCoordinate.
Camera pitch (tilt) in degrees. Only works with centerCoordinate.
Camera heading (bearing) in degrees. Only works with centerCoordinate.
options.styleURL
string
default:"StyleURL.Street"
The style URL to use for the snapshot.
If true, writes the snapshot to a temporary file and returns the file path. If false, returns a base64-encoded data URI.
Whether to include the Mapbox logo in the snapshot. Android only.
- File path (if
writeToDisk: true)
- Base64 data URI (if
writeToDisk: false)
Examples
Basic Snapshot
Save to Disk
Base64 Image
With Bounds
Without Logo (Android)
Share Snapshot
import { snapshotManager, StyleURL } from '@rnmapbox/maps';
import { Image } from 'react-native';
async function takeBasicSnapshot() {
const uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 300,
height: 200,
zoomLevel: 14,
styleURL: StyleURL.Streets,
});
// Display the snapshot
return <Image source={{ uri }} style={{ width: 300, height: 200 }} />;
}
import { snapshotManager } from '@rnmapbox/maps';
import RNFS from 'react-native-fs';
async function saveSnapshotToDisk() {
// Create a temp file
const uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 600,
height: 400,
zoomLevel: 12,
pitch: 30,
heading: 20,
styleURL: 'mapbox://styles/mapbox/dark-v10',
writeToDisk: true,
});
console.log('Snapshot saved to:', uri);
// Optionally move to a permanent location
const permanentPath = `${RNFS.DocumentDirectoryPath}/snapshot.png`;
await RNFS.moveFile(uri, permanentPath);
return permanentPath;
}
import { snapshotManager } from '@rnmapbox/maps';
import { Image } from 'react-native';
async function getBase64Snapshot() {
const base64Uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 300,
height: 200,
zoomLevel: 12,
styleURL: 'mapbox://styles/mapbox/satellite-v9',
writeToDisk: false, // Returns base64
});
// base64Uri is a data URI like "data:image/png;base64,..."
return <Image source={{ uri: base64Uri }} />;
}
import { snapshotManager } from '@rnmapbox/maps';
async function snapshotWithBounds() {
const uri = await snapshotManager.takeSnap({
bounds: [
[-74.126410, 40.797968],
[-74.143727, 40.772177],
],
width: 400,
height: 300,
styleURL: 'mapbox://styles/mapbox/outdoors-v11',
});
return uri;
}
import { snapshotManager } from '@rnmapbox/maps';
async function snapshotWithoutLogo() {
const uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 300,
height: 200,
zoomLevel: 12,
styleURL: 'mapbox://styles/mapbox/dark-v10',
withLogo: false, // Android only
});
return uri;
}
import { useState } from 'react';
import { View, Button, Image } from 'react-native';
import { snapshotManager } from '@rnmapbox/maps';
import Share from 'react-native-share';
function SnapshotSharer() {
const [snapshot, setSnapshot] = useState(null);
const takeAndShareSnapshot = async () => {
const uri = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 800,
height: 600,
zoomLevel: 14,
pitch: 45,
styleURL: 'mapbox://styles/mapbox/streets-v11',
writeToDisk: true,
});
setSnapshot(uri);
// Share the snapshot
await Share.open({
url: `file://${uri}`,
type: 'image/png',
});
};
return (
<View>
<Button title="Take & Share Snapshot" onPress={takeAndShareSnapshot} />
{snapshot && (
<Image
source={{ uri: snapshot }}
style={{ width: 300, height: 225 }}
/>
)}
</View>
);
}
Use Cases
Static Map Previews
Generate preview images for locations before showing the full interactive map:
const preview = await snapshotManager.takeSnap({
centerCoordinate: location,
width: 150,
height: 150,
zoomLevel: 13,
writeToDisk: false,
});
Sharing Locations
Create shareable images of map locations:
const shareImage = await snapshotManager.takeSnap({
centerCoordinate: [-74.006, 40.7128],
width: 800,
height: 600,
zoomLevel: 14,
pitch: 45,
heading: 90,
writeToDisk: true,
});
Thumbnails
Generate thumbnails for saved locations or routes:
const thumbnail = await snapshotManager.takeSnap({
bounds: routeBounds,
width: 200,
height: 150,
writeToDisk: false,
});
- Larger snapshots (width × height) take longer to generate
- Snapshots are generated asynchronously and don’t block the UI
- Consider caching snapshots if you need to display them multiple times
- Use
writeToDisk: true for large images to avoid memory issues with base64
- Base64 encoding increases the data size by ~33%
iOS
- Snapshots include the Mapbox logo by default
withLogo option has no effect
Android
- The
withLogo option can hide the Mapbox logo
- Ensure you comply with Mapbox Terms of Service when hiding the logo
- MapView - Interactive map component
- Camera - Control camera position (similar parameters)