React Native Model Viewer WebView

Direct answers

Fast facts for searchers and AI agents

Install

Installation

Expo apps should use Expo CLI so SDK-compatible native package versions can be selected when possible. Bare React Native apps can install the package pair with npm and follow react-native-webview native setup.

# Expo
npx expo install react-native-model-viewer-webview react-native-webview

# Bare React Native
npm install react-native-model-viewer-webview react-native-webview

Usage

Quick start

Pass a remote GLB URL, set a stable height, and enable the <model-viewer> controls you need.

import { ModelViewerWebView } from "react-native-model-viewer-webview";

export function Preview() {
  return (
    <ModelViewerWebView
      modelSource="https://example.com/car.glb"
      style={{ height: 320 }}
      htmlOptions={{
        autoRotate: true,
        cameraControls: true,
        exposure: 1.05,
        shadowIntensity: 0.35,
      }}
    />
  );
}

Model sources

Remote, local, and Expo Asset sources

<ModelViewerWebView
  modelSource="https://cdn.example.com/models/suv.glb"
  onModelLoaded={(status) => {
    console.log(status.message);
  }}
  onModelError={(status) => {
    console.warn(status.type, status.message);
  }}
/>

// metro.config.js
const { getDefaultConfig } = require("expo/metro-config");
const config = getDefaultConfig(__dirname);

config.resolver.assetExts = [
  ...config.resolver.assetExts,
  "glb",
  "gltf",
];

module.exports = config;

<ModelViewerWebView
  modelSource={require("./assets/car.glb")}
  style={{ height: 320 }}
/>

import { Asset } from "expo-asset";

const model = Asset.fromModule(require("./assets/model.glb"));
await model.downloadAsync();

<ModelViewerWebView modelSource={model} />

import { Asset } from "expo-asset";
import * as FileSystem from "expo-file-system/legacy";

const model = Asset.fromModule(require("./assets/model.glb"));
await model.downloadAsync();

const localUri = model.localUri ?? model.uri;
const base64 = await FileSystem.readAsStringAsync(localUri, {
  encoding: FileSystem.EncodingType.Base64,
});

<ModelViewerWebView
  modelSource={`data:model/gltf-binary;base64,${base64}`}
  style={{ height: 320 }}
/>

Compatibility

Verified smoke tests

These are manual smoke-test results, not a blanket support matrix. The Android local asset test used a bundled Khronos Box.glb, expo-asset, and a GLB data URI.

Runtime state

Events and errors

Use status callbacks for UI state, analytics, retry UX, and instrumentation around model loading.

<ModelViewerWebView
  modelSource={source}
  onStatus={(status) => track("model_status", status)}
  onModelLoaded={() => setReady(true)}
  onModelError={(status) => setError(status.message)}
/>

Offline

Offline script loading

The package now inlines a bundled @google/model-viewer runtime by default, so local model previews do not need a CDN request. Override the script only when you want a different runtime.

import { MODEL_VIEWER_CDN_SCRIPT_URL } from "react-native-model-viewer-webview";

<ModelViewerWebView
  modelSource="https://example.com/model.glb"
  htmlOptions={{
    modelViewerScriptUrl: MODEL_VIEWER_CDN_SCRIPT_URL,
  }}
/>

Use-case ideas

Where this package makes sense

AI agent support

Agent-friendly by default

The package ships AGENTS.md, llms.txt, and a portable SKILL.md folder. Claude Code can use it after copying the skill to a supported skills directory.

mkdir -p ~/.claude/skills
cp -R node_modules/react-native-model-viewer-webview/agent-skills/react-native-model-viewer-webview ~/.claude/skills/

Limitations

Known limitations

Package fit

Why this package exists

Native 3D renderers are the right answer for complex scenes. This package exists for the narrower case where an app needs a dependable single-model preview, simple controls, and a small React Native API without adopting a renderer as application infrastructure.