or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

accessibility.mdanimation.mdannotation.mdar.mdcontrols.mdenvironment.mdindex.mdloading.mdscene-graph.md
tile.json

tessl/npm-google--model-viewer

Web component for easily displaying interactive 3D models with AR support across browsers and devices

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@google/model-viewer@4.1.x

To install, run

npx @tessl/cli install tessl/npm-google--model-viewer@4.1.0

index.mddocs/

Model Viewer

Model Viewer is a web component that makes it easy to display interactive 3D models on the web and in AR. It provides a simple HTML element that can load glTF/GLB models with advanced features like lighting, animations, camera controls, and AR viewing modes.

Package Information

  • Package Name: @google/model-viewer
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @google/model-viewer

Core Imports

import '@google/model-viewer';
// The custom element <model-viewer> is now available

For dynamic imports and module access:

import { ModelViewerElement } from '@google/model-viewer';
// Access to the class directly

Three.js integration utilities:

import { CanvasTexture, FileLoader, Loader, NearestFilter } from '@google/model-viewer';
// Re-exported Three.js utilities

Basic Usage

<!-- Basic 3D model display -->
<model-viewer 
  src="models/astronaut.glb" 
  camera-controls
  touch-action="pan-y">
</model-viewer>

<!-- With AR support -->
<model-viewer 
  src="models/astronaut.glb" 
  ar 
  ar-modes="webxr scene-viewer quick-look"
  camera-controls
  touch-action="pan-y">
</model-viewer>

<!-- With animations -->
<model-viewer 
  src="models/robot.glb" 
  animation-name="walking"
  autoplay
  camera-controls>
</model-viewer>

Architecture

Model Viewer is built as a Lit-based web component with a modular mixin architecture:

  • ModelViewerElementBase: Core functionality for loading, rendering, and lifecycle management
  • Feature Mixins: Eight specialized mixins that add specific capabilities
  • Three.js Integration: Built on Three.js for 3D rendering with WebGL
  • WebXR Support: Native AR capabilities using WebXR APIs
  • Custom Element: Standard web component that works with any framework

The component registers as <model-viewer> and combines all features through mixin composition.

Capabilities

3D Model Loading

Load and display glTF/GLB 3D models with automatic optimization and caching.

interface LoadingInterface {
  src: string;
  poster: string;
  loading: 'auto' | 'lazy' | 'eager';
  reveal: 'auto' | 'interaction' | 'manual';
  withCredentials: boolean;
  
  dismissPoster(): void;
}

Model Loading and Display

Camera Controls and Interaction

Interactive camera controls with orbit, zoom, and pan functionality.

interface ControlsInterface {
  cameraControls: boolean;
  cameraOrbit: string;
  cameraTarget: string;
  fieldOfView: string;
  minCameraOrbit: string;
  maxCameraOrbit: string;
  interactionPrompt: 'auto' | 'when-focused' | 'none';
  orbitSensitivity: number;
  
  getCameraOrbit(): SphericalPosition;
  getCameraTarget(): Vector3D;
  jumpCameraToGoal(): void;
}

interface SphericalPosition {
  theta: number;
  phi: number;
  radius: number;
  toString(): string;
}

Camera Controls

Animation Playback

Control 3D model animations with playback options and crossfading.

interface AnimationInterface {
  autoplay: boolean;
  animationName: string | undefined;
  animationCrossfadeDuration: number;
  readonly availableAnimations: Array<string>;
  readonly paused: boolean;
  currentTime: number;
  
  play(options?: PlayAnimationOptions): void;
  pause(): void;
  appendAnimation(name: string, options?: AppendAnimationOptions): void;
}

Animation System

Augmented Reality (AR)

Enable AR viewing with WebXR, ARCore, and ARKit support.

interface ARInterface {
  ar: boolean;
  arModes: string;
  arScale: 'auto' | 'fixed';
  arPlacement: 'floor' | 'wall';
  readonly canActivateAR: boolean;
  
  activateAR(): Promise<void>;
}

Augmented Reality

Environment and Lighting

Configure lighting, shadows, and environment maps for realistic rendering.

interface EnvironmentInterface {
  environmentImage: string;
  skyboxImage: string;
  exposure: number;
  shadowIntensity: number;
  shadowSoftness: number;
  neutralLighting: boolean;
}

Environment and Lighting

Scene Graph Manipulation

Access and modify the loaded 3D model's scene graph, materials, and variants.

interface SceneGraphInterface {
  variantName: string;
  readonly availableVariants: Array<string>;
  orientation: string;
  scale: string;
  
  exportScene(options?: ExportOptions): Promise<Blob>;
  createTexture(uri: string): Promise<Texture | null>;
}

Scene Graph

Hotspots and Annotations

Add interactive hotspots and annotations positioned in 3D space.

interface AnnotationInterface {
  queryHotspot(name: string): HTMLElement | null;
  positionHotspot(hotspot: HTMLElement, position: Vector3D): void;  
  updateHotspot(config: HotspotConfiguration): void;
}

Hotspots and Annotations

Accessibility and Staging

Accessibility features and structured data generation.

interface StagingInterface {
  alt: string;
  generateSchema: boolean;
}

Accessibility

Core Types

type ModelViewerElement = InstanceType<typeof ModelViewerElement>;

type Vector3D = {
  x: number;
  y: number; 
  z: number;
  toString(): string;
};

type RGB = [number, number, number];
type RGBA = [number, number, number, number];

interface HotspotConfiguration {
  name: string;
  position: Vector3D;
  normal?: Vector3D;
  visible?: boolean;
}

interface PlayAnimationOptions {
  repetitions?: number;
  pingpong?: boolean;
}

interface ExportOptions {
  binary?: boolean;
  trs?: boolean;
  onlyVisible?: boolean;
  truncateDrawRange?: boolean;
  embedImages?: boolean;
  maxTextureSize?: number;
}

type ModelViewerTexture = any; // Three.js Texture wrapper

interface Material {
  name?: string;
  [key: string]: any;
}

interface Model {
  // Model scene graph access
  [key: string]: any;
}

interface GLTF {
  // glTF specification data structure
  [key: string]: any;
}

interface A11yTranslationsInterface {
  left: string;
  right: string;
  front: string;
  back: string;
  'upper-left': string;
  'upper-right': string;
  'upper-front': string;
  'upper-back': string;
  'lower-left': string;
  'lower-right': string;
  'lower-front': string;
  'lower-back': string;
}

interface Finger {
  x: number;
  y: number;
}

Core Methods

/**
 * Capture a screenshot of the current model view as a Blob
 * @param options - Optional configuration for image capture
 * @returns Promise that resolves to image Blob
 */
toBlob(options?: ToBlobOptions): Promise<Blob>;

interface ToBlobOptions {
  /** MIME type for the image (default: 'image/png') */
  mimeType?: string;
  /** Quality argument for lossy formats (0-1) */
  qualityArgument?: number;
  /** Whether to maintain ideal aspect ratio */
  idealAspect?: boolean;
}

Static Configuration

/**
 * Global configuration for all model-viewer instances
 */
interface ModelViewerStaticInterface {
  /** Location for DRACO mesh compression decoder */
  dracoDecoderLocation: string;
  /** Location for KTX2 texture transcoder */
  ktx2TranscoderLocation: string;
  /** Location for Meshopt decoder */
  meshoptDecoderLocation: string;
  /** Location for Lottie animation loader */
  lottieLoaderLocation: string;
  /** Maximum number of models to cache */
  modelCacheSize: number;
  /** Minimum render scale for performance */
  minimumRenderScale: number;
  
  /** Map all URLs through a callback function */
  mapURLs(callback: (url: string) => string): void;
}

Event System

Model Viewer dispatches custom events for various state changes and user interactions:

  • load - Model finished loading
  • progress - Loading progress updates
  • error - Loading or runtime errors
  • camera-change - Camera position/target changes
  • ar-status - AR mode status changes
  • model-visibility - Model visibility changes

All events include relevant detail data and can be handled with standard event listeners.