Skip to main content

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

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>
  );
}

Model Format Support

The Models component supports:
  • 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.

Performance Considerations

  • 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

Build docs developers (and LLMs) love