iJewel3D Viewer SDK

The iJewel Viewer library loads 3D models from your iJewel3D account by ID, exact name, or tag.

Tutorial

Check out Embed iJewel3D Models on Your Website for a step-by-step guide on how to use these functions.

To learn how to apply materials via URL parameters, see Apply Materials via URL.

Docs for older iJewel Drive instances

The documentation for iJewel Drive instances created before March 2025 is available here.

Loading a Specific Model by ID (loadModelById)

The primary function currently available for loading a single model directly from Drive is loadModelById. This is the recommended approach when you know the specific model file you want to display.

// Example: Load a model into a div with id="viewer-container"

// Ensure the viewer library script is loaded first
// <script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js"></script>
// <script src="https://releases.ijewel3d.com/libs/mini-viewer/0.6.17/bundle.nowebgi.iife.js"></script>

const driveBasename = 'drive'; // for enterprise clients contact us to get your basename, otherwise keep it unchanged
const modelFileId = 'xyz789abc123'; // Replace with the actual Model ID
const containerElement = document.getElementById('viewer-container');

ijewelViewer.loadModelById(
  modelFileId,
  driveBasename,
  containerElement,
  { // Optional ViewerOptions
    showCard: true,
    showLogo: true,
    // Add other options as needed
  }
);

// Optional: Listen for the ready event
window.addEventListener("ijewel-viewer-ready", (event) => {
  console.log("Viewer is ready:", event.detail.viewer);
  const viewerInstance = event.detail.viewer;
  // You can interact with the viewer instance here
});

Parameters

Parameter	Type	Required	Description
modelId	string	Yes	The unique File ID of the 3D model file within your Drive.
basename	string	Yes	The unique identifier for your iJewel Drive instance (e.g., 'yourcompany-drive'). Defaults to 'drive'. You don't need to change this one unless you are an enterprise client. Contact support if you don't know yours.
container	HTMLElement	Yes	The HTML element where the viewer canvas will be rendered.
options	ViewerOptions	No	An optional object containing viewer configuration options to customize appearance and behavior. See Viewer Class for details.

Loading a Model by Name (loadModelByName)

loadModelByName searches a folder tree for an exact file name. Public files do not require an authentication token.

For private files, provide a valid token. Contact iJewel3D support if your application does not have one.

// Example: Load a model named "ring_model.glb" from folder with ID "folder456"

// Ensure the viewer library script is loaded first
// <script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js"></script>
// <script src="https://releases.ijewel3d.com/libs/mini-viewer/0.6.17/bundle.nowebgi.iife.js"></script>

const modelName = 'ring_model.glb'; // Replace with the exact model filename
const parentFolderId = 'folder456'; // Replace with the ID of the parent folder
const driveBasename = 'drive'; // Or your enterprise basename
const authToken = undefined; // Public files do not need a token
const containerElement = document.getElementById('viewer-container');

const viewerInstance = await ijewelViewer.loadModelByName(
  modelName,
  parentFolderId,
  driveBasename,
  authToken,
  containerElement,
  { // Optional ViewerOptions
    showCard: true,
    // Add other options as needed
  }
);

Parameters (loadModelByName)

Parameter	Type	Required	Description
modelName	string	Yes	The exact file name, including its extension.
parentId	string	Yes	The folder ID that scopes the search. The search includes nested folders.
basename	string	Yes	The iJewel3D instance identifier. Standard accounts use drive.
token	string	No	An authentication token for a private file. Public files do not need one.
container	HTMLElement	Yes	The HTML element that contains the viewer canvas.
options	ViewerOptions	No	The viewer configuration. See Viewer Class.

Loading a Model by Tag (loadModelByTag)

loadModelByTag searches a folder tree for a matching public file. Use a unique tag within that folder tree.

This function does not accept an authentication token. The selected file must be public.

// Example: Load the public model tagged "pid-12345"

// Make sure that the viewer library scripts are loaded first
// <script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js"></script>
// <script src="https://releases.ijewel3d.com/libs/mini-viewer/0.6.17/bundle.nowebgi.iife.js"></script>

const tag = 'pid-12345';
const scope = 'folder456';
const driveBasename = 'drive';
const containerElement = document.getElementById('viewer-container');

const viewerInstance = await ijewelViewer.loadModelByTag(
  tag,
  scope,
  driveBasename,
  containerElement,
  {
    showCard: true,
  }
);

Parameters (loadModelByTag)

Parameter	Type	Required	Description
tag	string	Yes	The exact tag assigned to the public file.
scope	string	Yes	The folder ID that scopes the search. The search includes nested folders.
basename	string	Yes	The iJewel3D instance identifier. Standard accounts use drive.
container	HTMLElement	Yes	The HTML element that contains the viewer canvas.
options	ViewerOptions	No	The viewer configuration. See Viewer Class.

Cross-Origin Resource Sharing (CORS)

CORS settings restrict Mini Viewer SDK requests to authorized domains.

If the console shows a CORS error, ask iJewel3D support to authorize your hosting domain.

React (ViewerComponent)

A complete, runnable example project containing this component is available on GitHub: https://github.com/maanHimself/ijewel-viewer-react-example

1. Update package.json

Add the following lines to your dependencies:

{
  "dependencies": {
    // ... other dependencies
    "@ijewel3d/mini-viewer": "https://releases.ijewel3d.com/libs/web/ijewel3d-mini-viewer-0.6.17.tgz",
    "@types/webgi": "https://releases.ijewel3d.com/libs/webgi-v0/bundle-types-0.22.0.tgz"
  }
}

2. Install Dependencies

npm install

3. Add WebGI Script

Add the WebGI script before your React app bundle loads.

<script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js"></script>

4. Usage

Import the ViewerComponent from the library and use it in your React application. Provide the necessary props to load your model.

import { ViewerComponent } from "@ijewel3d/mini-viewer";
import { useEffect, useState } from "react";
import type { ViewerApp } from "webgi";

function App() {
  const [modelId,] = useState("Ep9bWZIlTSG6_8DH7QDc1w"); // Replace with your actual model ID
  const [viewer , setViewer] = useState<ViewerApp | null>(null);
  
  useEffect(() => {
    //optionally, you can use the viewer for further customization
    if (viewer) {
      // Example: Set background color
      const Color = (window as any).Color;
      viewer.scene.backgroundColor = new Color("#232721");
    }
  }, [viewer]);

  return (
    <div style={{ width: "100vw", height: "100vh" }}>

      <ViewerComponent
        modelId={modelId}
        onViewerReady={(v : ViewerApp) => setViewer(v)}
        viewerOptions={{
          showCard: false,
          //add other viewer options here
        }}
        basename="drive" //optional for enterprise users
      />

    </div>
  );
}
export default App;

Next.js

The viewer relies on window, WebGL, and other browser‑only APIs, therefore server‑side rendering (SSR) for the component must be disabled when using Next.js. Add the WebGI script once in your root layout, then load the viewer component with next/dynamic.

import Script from "next/script";
import type { ReactNode } from "react";

export default function RootLayout({ children }: { children: ReactNode }) {
  return (
    <html lang="en">
      <body>
        <Script src="https://releases.ijewel3d.com/libs/webgi-v0/bundle-0.22.0.js" strategy="beforeInteractive" />
        {children}
      </body>
    </html>
  );
}

"use client";
import dynamic from "next/dynamic";

// Dynamically import the Viewer component to avoid SSR issues
const ViewerComponent = dynamic(() => import("@ijewel3d/mini-viewer").then((mod) => mod.ViewerComponent), {
  ssr: false,
});

const myModelId = "ThWX3yXbSqygIcRbS2ODGw"; // Replace with your actual model ID

export default function Home() {
  return (
    <div style={{ width: "100vw", height: "100vh" }}>
        <ViewerComponent modelId={myModelId} />
    </div>
  );
}

TIP

This page will be updated as additional functions for interacting with iJewel Drive are introduced

Component Props (ViewerComponent)

The ViewerComponent accepts the following props to configure its behavior and appearance:

Prop	Type	Optional/Required	Description
project	Project	Optional	A full project configuration object. If provided, this takes precedence over modelId and modelName/parentId. You can use this to load local 3d files. See Viewer Class
modelId	string	Optional	The unique File ID of a specific model in iJewel Drive. Used if project is not provided. This is the simplest way to load a single model.
modelName	string	Optional	The exact file name. Use it with parentId. Public files do not require token.
parentId	string	Optional	The folder ID for a modelName search.
tag	string	Optional	The exact tag for a public-file search.
scope	string	Required with tag	The folder ID for a tag search.
basename	string	Optional	The basename identifier for your iJewel Drive instance. Only change this if you are an enterprise client with a custom basename.
token	string	Optional	An authentication token for a private file selected by modelName and parentId.
viewerOptions	ViewerOptions	Optional	An object containing options to customize the viewer's appearance and behavior (e.g., showCard, showLogo ). See Viewer Class documentation for details.
onError	(err: Error) => void	Optional	A callback function that gets executed if an error occurs during model loading or viewer initialization. Receives the Error object as an argument.
onLoad	(viewer: Viewer ) => void	Optional	A callback function executed when the iJewel Viewer helper class instance (which manages loading and wrapping WebGi) is successfully initialized or updated after loading a model. Receives the IjewelViewerClass instance. Note: This is distinct from onViewerReady.
onViewerReady	(viewer: ViewerApp) => void	Optional	A callback function executed when the underlying WebGi ViewerApp instance is fully initialized and ready for interaction (e.g., scene manipulation, adding plugins). Receives the ViewerApp instance. This often fires shortly after onLoad.
className	string	Optional	A standard React prop to apply a CSS class to the root div element rendered by the component.
style	React.CSSProperties	Optional	A standard React prop to apply inline CSS styles to the root div element. Default styles ensure the viewer attempts to fill its container.

To load a model, you must provide one of the following combinations:

1. The project prop.
2. The modelId prop.
3. The modelName and parentId props together. Add token for a private file.
4. The tag and scope props together.