Documentation Index
Fetch the complete documentation index at: https://mintlify.com/rnmapbox/maps/llms.txt
Use this file to discover all available pages before exploring further.
Models
The Models component registers 3D model assets to be used in the map. Models can be referenced by model layers to display 3D objects on the map.
Import
import { Models } from '@rnmapbox/maps';
Basic Usage
import { MapView, Models, ModelLayer } from '@rnmapbox/maps';
function MapWith3DModels() {
return (
<MapView style={{ flex: 1 }}>
<Models
models={{
car: 'https://example.com/models/car.gltf',
building: require('./assets/building.glb'),
}}
/>
<ModelLayer
id="3d-models"
sourceId="modelSource"
style={{ modelId: 'car' }}
/>
</MapView>
);
}
Props
models
models
{ [key: string]: string | number }
required
Pairs of model names to GLTF/GLB file paths, URLs, or asset IDs.Keys are the model names that will be used to reference the model in layer styles. Values can be:
- URL strings pointing to
.gltf or .glb files
- Asset IDs from
require() statements
- Local file paths (with
file:// prefix)
<Models
models={{
// URL to GLTF model
car: 'https://example.com/models/car.gltf',
// URL to GLB model
building: 'https://example.com/models/building.glb',
// Required asset (GLB)
tree: require('./assets/models/tree.glb'),
// Required asset (GLTF)
furniture: require('./assets/models/furniture.gltf'),
// Local file path
monument: 'file:///path/to/monument.glb',
}}
/>
Examples
Basic 3D Models
Multiple Models
Dynamic Models
Animated Models
import { MapView, Models, ModelLayer, ShapeSource } from '@rnmapbox/maps';
function Basic3DModels() {
const modelLocations = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [-122.4194, 37.7749],
},
properties: {
modelId: 'car',
},
},
],
};
return (
<MapView style={{ flex: 1 }}>
<Models
models={{
car: 'https://example.com/models/car.glb',
}}
/>
<ShapeSource id="modelLocations" shape={modelLocations}>
<ModelLayer
id="3d-cars"
style={{
modelId: ['get', 'modelId'],
modelScale: [1, 1, 1],
modelRotation: [0, 0, 90],
}}
/>
</ShapeSource>
</MapView>
);
}
import { MapView, Models, ModelLayer, ShapeSource } from '@rnmapbox/maps';
function MultipleModels() {
const modelData = {
type: 'FeatureCollection',
features: [
{
type: 'Feature',
geometry: { type: 'Point', coordinates: [-122.4194, 37.7749] },
properties: { type: 'car' },
},
{
type: 'Feature',
geometry: { type: 'Point', coordinates: [-122.4184, 37.7739] },
properties: { type: 'tree' },
},
{
type: 'Feature',
geometry: { type: 'Point', coordinates: [-122.4204, 37.7759] },
properties: { type: 'building' },
},
],
};
return (
<MapView style={{ flex: 1 }}>
<Models
models={{
car: require('./assets/models/car.glb'),
tree: require('./assets/models/tree.glb'),
building: 'https://example.com/models/building.glb',
}}
/>
<ShapeSource id="models" shape={modelData}>
<ModelLayer
id="3d-objects"
style={{
modelId: ['get', 'type'],
modelScale: [1, 1, 1],
}}
/>
</ShapeSource>
</MapView>
);
}
import { useState } from 'react';
import { MapView, Models, ModelLayer, ShapeSource } from '@rnmapbox/maps';
import { Button } from 'react-native';
function DynamicModels() {
const [models, setModels] = useState({
default: require('./assets/models/default.glb'),
});
const addModel = (name: string, url: string) => {
setModels((prev) => ({
...prev,
[name]: url,
}));
};
return (
<>
<MapView style={{ flex: 1 }}>
<Models models={models} />
<ShapeSource id="modelPoints" shape={pointsGeoJSON}>
<ModelLayer
id="3d-models"
style={{
modelId: ['get', 'modelName'],
modelScale: [1, 1, 1],
}}
/>
</ShapeSource>
</MapView>
<Button
title="Add Car Model"
onPress={() => addModel('car', 'https://example.com/car.glb')}
/>
</>
);
}
import { MapView, Models, ModelLayer, ShapeSource } from '@rnmapbox/maps';
function AnimatedModels() {
const vehicleLocation = {
type: 'Feature',
geometry: {
type: 'Point',
coordinates: [-122.4194, 37.7749],
},
properties: {
bearing: 90,
},
};
return (
<MapView style={{ flex: 1 }}>
<Models
models={{
car: require('./assets/models/car-animated.glb'),
}}
/>
<ShapeSource id="vehicle" shape={vehicleLocation}>
<ModelLayer
id="animated-car"
style={{
modelId: 'car',
modelScale: [1, 1, 1],
modelRotation: [0, 0, ['get', 'bearing']],
modelOpacity: 1,
}}
/>
</ShapeSource>
</MapView>
);
}
- GLTF (
.gltf) - Text-based format with external resources
- GLB (
.glb) - Binary format with embedded resources (recommended for better performance)
Models should follow the glTF 2.0 specification.
- Use GLB format instead of GLTF for better loading performance
- Keep model file sizes small (under 1MB when possible)
- Reduce polygon count for models that will be displayed at small scales
- Consider using LOD (Level of Detail) techniques for complex models
- Cache models locally when possible instead of loading from remote URLs