EditorJS 3D Media Block

An EditorJS block tool for displaying interactive 3D models in various formats (glTF, GLB, USDZ, and more). Perfect for e-commerce product displays, educational content, engineering documentation, and WebXR experiences.

📺 Live Demo

Features

• 📦 Multiple 3D formats - Support for GLB, glTF, USDZ, OBJ, FBX, and more
• 🎨 Customizable viewers - Choose between ModelViewer or ThreeJS renderers
• 🔄 Interactive controls - Built-in orbit, zoom, and rotation controls
• 📱 iOS AR support - Optional USDZ models for AR Quick Look
• 🖼️ Poster images - Fallback images for better loading experience
• ✍️ Captions - Optional editable captions below 3D models
• 🎯 File validation - Custom validation before upload
• 🔌 Flexible upload - Custom upload handlers for any backend
• 🎭 Custom loaders - Replace default loading UI with your own
• ⚙️ Custom attributes - Add any HTML attributes to the viewer element

Installation

npm install editorjs-3d-media

If using ModelViewer (default), also include the ModelViewer library:

npm install @google/model-viewer

Or via CDN:

<script type="module" src="https://ajax.googleapis.com/ajax/libs/model-viewer/3.0.0/model-viewer.min.js"></script>

Usage

Basic Setup

import EditorJS from '@editorjs/editorjs';
import Media3D from 'editorjs-3d-media';

const editor = new EditorJS({
  holder: 'editorjs',
  tools: {
    media3d: {
      class: Media3D,
      config: {
        uploadFile: async (file) => {
          // Upload file to your server
          const formData = new FormData();
          formData.append('file', file);
          
          const response = await fetch('/upload', {
            method: 'POST',
            body: formData
          });
          
          const data = await response.json();
          return {
            url: data.url, // Required: URL to the 3D model
            viewer: 'modelviewer', // Required: viewer type
            otherAttributes: { // Optional: additional attributes for the viewer element
              poster: data.posterUrl,
              'ios-src': data.iosSrcUrl
            }
          };
        }
      }
    }
  }
});

Advanced Configuration

const editor = new EditorJS({
  tools: {
    media3d: {
      class: Media3D,
      config: {
        viewer: 'modelviewer',
        formatsAllowed: ['glb', 'gltf', 'usdz', 'obj'],
        enableCaption: true,
        autoOpenFilePicker: true,
        
        viewerStyle: {
          width: '100%',
          height: '500px',
          borderRadius: '12px',
          backgroundColor: '#f0f0f0'
        },
        
        uploadFile: async (file) => {
          // Your upload logic
          return {
            url: 'https://example.com/model.glb',
            viewer: 'modelviewer',
            otherAttributes: {
              poster: 'https://example.com/poster.jpg',
              'ios-src': 'https://example.com/model.usdz'
            }
          };
        },
        
        validateFile: (file) => {
          const maxSize = 50 * 1024 * 1024; // 50MB
          if (file.size > maxSize) {
            return 'File size must be less than 50MB';
          }
          return true;
        },
        
        customLoaderElement: (file) => {
          const loader = document.createElement('div');
          loader.innerHTML = `
            <div style="text-align: center; padding: 40px;">
              <div class="spinner"></div>
              <p>Uploading ${file.name}...</p>
            </div>
          `;
          return loader;
        }
      }
    }
  }
});

Output Data Format

When you save the editor content, the 3D Media block will return data in this format:

{
  type: "media3d",
  data: {
    viewer: "modelviewer",
    caption: "My 3D Model",
    file: {
      url: "https://example.com/model.glb"
    },
    attributes: {
      poster: "https://example.com/poster.jpg",
      "ios-src": "https://example.com/model.usdz"
    }
  }
}

Important Details

Viewer Types

ModelViewer (Default)

• Uses Google's <model-viewer> web component
• Best for web compatibility and AR support
• Supports GLB, glTF, and USDZ formats
• Includes built-in controls and AR Quick Look for iOS
• Requires: @google/model-viewer library to be loaded

ThreeJS

• Uses Three.js for rendering
• More customizable but requires manual setup
• Note: Currently requires you to implement the rendering logic

File Upload

The uploadFile function must return a Promise that resolves to an object with:

• url (required): URL to the 3D model file
• viewer (required): The viewer type to use ('modelviewer' or 'threejs')
• otherAttributes (optional): Object containing additional HTML attributes to add to the viewer element
  • For ModelViewer, common attributes include poster (preview image) and ios-src (USDZ for AR Quick Look)
  • These attributes are applied directly to the viewer element (e.g., <model-viewer poster="..." ios-src="...">)

File Validation

The validateFile function should:

• Return true if the file is valid
• Return a string with an error message if invalid
• Receive the File object as parameter

Caption Support

When enableCaption is true:

• Users can add/edit captions below the 3D viewer
• Captions are saved with the block data
• Captions respect read-only mode

Auto-Open File Picker

When autoOpenFilePicker is true (default):

• File picker opens automatically when creating a new block
• Only triggers on first render
• Does not apply in read-only mode

Read-Only Mode

The block fully supports EditorJS read-only mode:

• Captions become non-editable
• Upload button is hidden
• Shows "No 3D model provided" message if no data exists

Configuration Options

Name	Description	Type	Default
viewer	3D viewer library to use	'modelviewer' | 'threejs'	'modelviewer'
formatsAllowed	Array of allowed 3D file format extensions	string[]	['glb', 'gltf']
enableCaption	Enable caption input below the 3D viewer	boolean	true
autoOpenFilePicker	Automatically open file picker on first render when empty	boolean	true
viewerStyle	Custom CSS styles for the 3D viewer element	Partial<CSSStyleDeclaration>	undefined
uploadFile	Function to handle file upload to your server	(file: File) => Promise<{url: string, viewer: Viewer, otherAttributes?: Record<string, string>}>	undefined
validateFile	Function to validate file before upload	(file: File) => boolean | string	undefined
customLoaderElement	Custom HTML element to show during upload	(file: File) => HTMLElement	undefined

Browser Support

• Modern browsers with ES6+ support
• ModelViewer requires browsers that support Web Components
• iOS AR Quick Look requires iOS 12+ and Safari

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Credits

Built with:

• EditorJS
• Google Model Viewer (optional)
• CodeX Icons