Example 1: Props-Based API (Backward Compatible)

Simple props-based usage with auto-rotate and toon shading. Perfect for quick embedding without custom controls.

• Auto-Rotate - Model rotates automatically
• Toon Shading - Cel-shaded anime look
• Default Controls - Standard control panel with common features

Example 2: Compound Components (Custom Layout)

Full control over layout and which controls to show using compound components. Build your own custom control panel with only the features you need.

Example 3: Minimal Embedded Viewer

Compact viewer with no controls - just the model with auto-rotation. Perfect for inline embedding in blog posts or character showcases.

Note: If a model appears without textures, check that textures are properly embedded in the GLB file during export from Blender. See public/models/README.md for troubleshooting.

Example 4: Full Animation Controls

Advanced animation control with full playback UI including play/pause/stop, speed control, and loop modes. Perfect for character showcases with multiple animations.

Example 5: Debug Mode with Helpers

Debug mode provides visualization helpers for development - bounding box, grid/axes, and light helpers. Use controlTier="debug" to show all debug controls.

Benefits of the New API

• ✅ Flexible - Mix and match controls to build custom UIs
• ✅ Backward Compatible - Props-based API still works
• ✅ Redux-like State - Predictable state management with useReducer
• ✅ Compound Components - Compose your own control panels
• ✅ Promise-based Animations - Async/await for animation control
• ✅ Theme-aware - Automatically adapts to light/dark mode
• ✅ TypeScript - Full type safety with discriminated unions

Next Steps

• Add your FBX, GLTF, or GLB models to public/models/
• Choose props-based API for quick embedding or compound components for custom layouts
• Use compound components to build exactly the control panel you need
• Embed the viewer in your comic pages or blog posts
• See /3d-animation-test for animation examples

Using in MDX Content

To use the 3D viewer in MDX comic pages or blog posts, you need to import it at the top of your MDX file.

Simple Props-Based Usage (Recommended for MDX)

---
title: "My 3D Model Post"
# ... other frontmatter
---

import ModelViewer from '@components/react/3d';

# Check Out This 3D Model!

Here's my character model with auto-rotate and cel-shading:

<ModelViewer 
  client:load
  modelPath="/models/my-character.glb"
  height="600px"
  autoRotate={true}
  toonShading={true}
  showControls={true}
/>

Pretty cool, right?

Compound Components in MDX (Advanced)

For compound components, create a React wrapper component first:

// src/components/react/CharacterViewer.tsx
import ModelViewer, { 
  ViewerCanvas, 
  ViewerControls, 
  ViewControl,
  CameraControl,
  AnimationControl 
} from '@components/react/3d';

export const CharacterViewer = ({ modelPath }: { modelPath: string }) => (
  <ModelViewer modelPath={modelPath}>
    <ViewerCanvas height="700px" />
    <ViewerControls title="Character Controls">
      <ViewControl.AutoRotate />
      <ViewControl.ToonShading />
      <CameraControl.PresetList />
      <AnimationControl.Player />
    </ViewerControls>
  </ModelViewer>
);

Then use it in your MDX:

---
title: "Character Showcase"
---

import { CharacterViewer } from '@components/react/CharacterViewer';

# Meet My Character

<CharacterViewer 
  client:load 
  modelPath="/models/my-character.glb" 
/>

Available Props for MDX Usage

Tips for MDX Usage

• ✅ Always use client:load directive for interactivity
• ✅ Place models in public/models/ for easy paths
• ✅ Use props-based API for simple embedding
• ✅ Create wrapper components for custom compound layouts
• ✅ Test in both light and dark mode (viewer is theme-aware)
• ⚠️ GLB models with Blender cameras will have preset buttons automatically