Methane@methane-ui/*
CSS LayoutsComponentsSkillsTheme BuilderGitHub
← All Components

<mth-model-viewer>

@methane-ui/3d~9.0 KB brotli shell + lazy engine~2.6 KB shell · lazy engine chunk

Wrap-first Three.js <mth-model-viewer> component featuring lazy WebGL/WebGPU renderer attachment, keyboard orbit/zoom/reset controls, MotionController reduced-motion gating on autoRotate, URL sanitization, and poster/fallback slots.

When NOT to use: Use a lightweight @methane-ui/css layout class instead of a custom element when static CSS suffices.

Live Interactive Preview

Interactive StageLive Custom Element · <mth-model-viewer> (@methane-ui/3d)
3D Stage Ready (WebGL with automatic headless fallback)
Ready · interact with <mth-model-viewer>, or toggle Theme, Direction (LTR/RTL), or props above.

Multi-Framework Playground & Snippets

<script type="module" src="@methane-ui/3d/model-viewer"></script>
<mth-model-viewer renderer-backend="auto" auto-rotate-speed="2"></mth-model-viewer>

Properties & Attributes

PropertyAttributeTypeDefaultDescription
srcsrcstring""glTF/GLB model URL (validated with @methane-ui/sanitize isSafeUrl).
posterposterstring""Optional preview poster image URL shown until the 3D scene loads.
altaltstring""Accessible description of the 3D model.
rendererBackendrenderer-backend'auto' | 'webgl' | 'webgpu'"auto"Preferred Three.js rendering backend (auto, webgl, or webgpu).
autoRotateauto-rotatebooleanfalseEnables continuous camera turntable rotation (disabled automatically under prefers-reduced-motion: reduce).
autoRotateSpeedauto-rotate-speednumber2Turntable rotation speed multiplier.
cameraOrbitThetacamera-orbit-thetanumber0Horizontal camera azimuth angle in degrees.
cameraOrbitPhicamera-orbit-phinumber75Vertical camera polar angle in degrees.
cameraDistancecamera-distancenumber4Camera orbit distance from origin.
exposureexposurenumber1Tone-mapping exposure multiplier.
showControlsshow-controlsbooleantrueShows interactive accessible camera toolbar controls.
loadingloadingbooleanfalseIndicates active model/renderer loading.
errorerrorstring""Error message when model load or URL validation fails.

Events

EventDetail TypeDescription
mth-model-load{ src: string; backend: 'webgpu' | 'webgl' | 'headless' }Emitted when the Three.js model finishes loading.
mth-camera-change{ theta: number; phi: number; distance: number }Emitted when camera orbit or zoom updates.
mth-model-error{ message: string }Emitted when model URL validation or glTF load fails.

APG Keyboard Matrix

KeyDirectionWhenExpected Behavior
ArrowLeftltr3D viewport is focusedorbits camera left
ArrowRightltr3D viewport is focusedorbits camera right
ArrowUpboth3D viewport is focusedtilts camera upward
ArrowDownboth3D viewport is focusedtilts camera downward
+both3D viewport is focusedzooms camera closer
-both3D viewport is focusedzooms camera farther
Homeboth3D viewport is focusedresets camera orbit and distance

Accessibility Checklist

CategoryRequirementVerified By
ariaAll aria-* IDREFs resolve within the same DOM root (ADR-003).scanSameRootAria
focusdelegatesFocus: true with zero host internals.role (ADR-014).lint-plugin & spec-compiler
contrastRenders legible borders, focus outlines, and selection indicators under forced-colors: active.Playwright forced-colors matrix
keyboardImplements all 7 APG keyboard transitions across LTR/RTL.mth-model-viewer.spec.test.ts
statesExposes ElementInternals CustomStateSet flags: :state(loading), :state(error), :state(loaded), :state(auto-rotating), :state(reduced-motion).Conformance suite
i18nRoutes 8 UI/ARIA strings through @methane-ui/core i18n catalog.Locale context test