Viewer API Reference

The Viewer class is responsible for initializing and rendering the iJewelMiniViewer in a specified container.

Constructor

constructor(container: HTMLElement, project: Project, options?: ViewerOptions)

• Parameters:
  • container: The HTML element in which the viewer will be rendered.
  • project: An object containing the project configuration details.
  • options: An optional object containing various viewer options.

Methods

render(project: any)

• Parameters:

  • project: The project configuration to be rendered.

• Description: Renders the viewer with the given project configuration. This method sets up the viewer with the specified options and displays the UI components. To update the project and the 3D model, call viewer.render(project). This will clear the previous project and render the new one.

TIP

You can call viewer.render(newProject) to load new models and clear the previous scene on the same Viewer instance.

Configurator Try-On Helpers

Mini Viewer's standard Try-On button prepares the current configured ring automatically. Use these helpers only when your integration supplies its own Try-On button and calls RingTryonPlugin.start() directly.

Export	Returns	Description
getConfiguratorTryonRingChoices(viewerApp)	{ id: string; label: string }[]	Lists the visible Ring Configurator or Wedding Band Builder rings available for Try-On.
prepareConfiguratorTryon(viewerApp, tryon, { ringId? })	{ ringId?: string; restore(): void }	Prepares one configured ring for the plugin and returns an idempotent restore handle. Without ringId, it uses the current ring.

Both functions are exported from @ijewel3d/mini-viewer and are available on window.ijewelViewer in the IIFE bundle.

prepareConfiguratorTryon() throws a RangeError for a ringId that getConfiguratorTryonRingChoices() does not list, so always take the id from that call rather than from storage. It throws a TypeError for a viewer or plugin it cannot use. For a plain model it prepares nothing and returns a restore handle that does nothing, because a plain model needs no preparation.

import {
  getConfiguratorTryonRingChoices,
  prepareConfiguratorTryon
} from "@ijewel3d/mini-viewer";

Start Try-On from a custom button

This IIFE example assumes that Mini Viewer has created viewerApp, the ijewel-scene-ready event has fired, Web VTO is loaded, and tryonConfig contains the saved fit. If more than one ring is returned, provide a picker in your interface.

<button id="tryon-button" type="button">Try On</button>

const tryonButton = document.getElementById("tryon-button");

async function startConfiguratorTryon() {
  const tryon = await viewerApp.getOrAddPlugin(
    ij_vto.RingTryonPlugin
  );

  const ringChoices = ijewelViewer.getConfiguratorTryonRingChoices(viewerApp);
  const selectedRing = ringChoices.length > 1
    ? await showRingPicker(ringChoices) // Implement this in your interface.
    : ringChoices[0];

  if (!selectedRing) {
    throw new Error("The customer did not select a ring.");
  }

  await tryon.fromJSON({
    ...tryonConfig,
    type: ij_vto.RingTryonPlugin.PluginType
  });

  const session = ijewelViewer.prepareConfiguratorTryon(
    viewerApp,
    tryon,
    { ringId: selectedRing.id }
  );

  try {
    await tryon.start();
  } catch (error) {
    session.restore();
    throw error;
  }
}

tryonButton.addEventListener("click", () => {
  startConfiguratorTryon().catch(console.error);
});

Call the example from a customer click or tap so the browser can request camera permission. The session restores the complete configurator after Try-On stops, setup mode exits, startup fails, camera permission is denied, or the device is unsupported. Do not call restore() immediately after a successful start. If your integration cancels before start(), call it explicitly.

Check tryon.running after start()

On a device with no camera, start() can resolve without an error and leave tryon.running as false. The session still restores the configurator on its own, so the scene is safe. Read tryon.running to decide whether to show your Try-On interface or a fallback message.

See RingTryonPlugin for configuration and lifecycle methods.

ViewerOptions

The ViewerOptions interface provides several optional properties to control the appearance and behavior of the viewer.

Property	Type	Description	Default
viewer	ViewerApp	An existing viewer instance to be used for rendering. If not provided, a new viewer will be created.	undefined
showLogo	boolean	Determines whether the logo is displayed in the viewer.	true
showCard	boolean	Controls the visibility of the floating card that displays model details.	true
showSwitchNode	boolean	Show or hide swich nodes from the configurator.	false
splitMaterialTabs	boolean	Determines if material options are displayed in separate tabs.	undefined
hideQuality	boolean	Controls the visibility of quality settings in the UI.	false
logoScale	number	Specifies the scale of the logo.	1
logoPositionX	number	Determines the horizontal position of the logo on the screen. The value ranges from 0 to 1, where 0 positions the logo at the far left and 1 positions the logo at the far right.	1
logoPositionY	number	Similar to logoPositionX but vertically	0
showZoomButtons	boolean	Determines whether zoom buttons are displayed in the viewer.	false
showUiButtons	boolean	Determines whether ui buttons bar is displayed in the viewer.	true
enableZoom	boolean	Enables or disables zoom functionality.	true
enableScrollWheel	boolean	Enables or disables zooming with the scroll wheel.	true
hideCameraViews	boolean	Hides the UI button for switching between defined camera views.	false
hideRotateCamera	boolean	Hides the UI button for toggling automatic camera rotation.	false
hideGltfAnimations	boolean	Hides the UI controls for playing embedded GLTF animations.	false
hideFitScene	boolean	Hides the UI button used to reset the camera and fit the model to the view.	false
hideFullScreen	boolean	Hides the UI button for toggling fullscreen mode.	false
showProfile	boolean	Displays a profile section using profileName, profileUrl, etc., from the Project config.	false
shareUrl	string	Overrides the default URL used by the share button.	window.location.href
autoGroundTonemap	boolean	Automatically applies tonemapping to the ground plane, to match the background tonemaping.	false
showShareButton	boolean	Controls the visibility of the share button in the UI.	false
showConfigurator	boolean	Controls the visibility of the entire configurator UI panel.	true
showPosterInLoadingScreen	boolean	Determines if the posterUrl from the Project config should be displayed while the 3D model is loading.	true
disableInteractionPrompt	boolean	Disables the initial overlay hand prompt that instructs users how to interact with the model.	false
runRotateCamera	boolean	Starts the turntable camera rotation immediately after the model loads.	false
headerComponent	React.ReactNode	Allows injecting a custom React component into the viewer's header area.	undefined
transparentBg	boolean	Makes the background of the viewer's canvas transparent instead of using a scene background. identical to clipBackground.	false
isModal	boolean	Indicates if the viewer is being rendered within a modal context, potentially altering some UI behavior or layout.	false
hideNameNumbers	boolean	Hides automatically generated numerical suffixes from option names displayed in the configurator.	false
configuratorBottomOffsetPx	number	Adds a specified pixel offset to the bottom of the configurator UI, useful for avoiding overlap with other fixed elements.	undefined
useDefaultVJSON	boolean	If true, attempts to load a default scene configuration (vjson) if one isn't explicitly provided in the project config.	false
hideTryOn	boolean	Hides the virtual Try-On button. The button appears only for projects that enable Try-On. See Direct Integration.	false
tryonPath	string	URL of the web-vto script that Mini Viewer loads when the customer starts Try-On. Set it to pin a specific Web VTO release, or when iJewel3D supplies a different bundle URL.	The release bundled with this Mini Viewer
wbbDesignHost	object	Persists saved Wedding Band designs in the project instead of the browser. See The project design catalogue.	undefined
wbbShareBaseUrl	string	Storefront address that a Wedding Band design link is built on. Set it when the builder runs in a cross-origin iframe. Same effect as setShareBaseUrl().	The page address

Project Configuration

When initializing the iJewel Viewer, you need to provide a project configuration object that includes various settings for your 3D model, environment, materials, and more. Below is a detailed explanation of the properties that can be included in the project configuration object.

Project Properties

Property	Type	Description
modelUrl	string	URL of the 3D model file (e.g., a .glb file).
basePath	string	Base URL path where your assets are stored. Can be an empty string if not needed.
posterUrl	string	URL of the poster image.
logo	string	URL of the logo to be displayed in the viewer.
name	string	Name of the project.
description	string	Description of the project.
sceneConfig	object	Configuration for the scene environment, including background and ground settings.
cameraConfig	object	Configuration for the camera settings.
materialConfig	object	Configuration for the materials used in the model.
configuratorConfig	array	[Deprecated] Use plugins["MaterialConfiguratorPlugin"] instead. Configuration for the configurator options available in the viewer.
plugins	object	Configuration for the plugins used in the viewer.
tryonConfig	object	Virtual Try-On settings for a model or configurator project. Requires enabled: true for the viewer to offer Try-On. See Prepare a Try-On Project.
category	string	Specify the category of the model, e.g. Ring, Necklace or Watch.
tags	string[]	An array of strings containing tags for the model.
profileName	string	The name to be displayed on the profile card (used when ViewerOptions.showProfile is true).
profileUrl	string	A URL associated with the profile (e.g., website, portfolio link), used in the profile card.
profileDescription	string	Descriptive text for the profile card.
profileImage	string	URL for the image to be displayed on the profile card.
version	string	A version identifier for the assets and configurator format (e.g., "v6").
currentPose	{ position: number[]; rotation: [number, number, number, EulerOrder] } | null	Specifies an initial pose (position and rotation of the 3d model) to set when the viewer loads. Set to null to disable.
shouldApplyModelStageConfig	boolean	Indicates whether the viewer settings included with the specifed model stage in sceneConfig (like background color or related configs) should be applied on load.

Detailed Explanation

• modelUrl: The URL pointing to the 3D model file you want to load.
• basePath: The base path for your assets, which can be left empty if not needed.
• posterUrl: The URL of the poster image to be displayed before the model loads.
• logo: The URL of the logo image to be displayed within the viewer.
• name: name of the model to be displayed in the floating card.
• description: A brief description of the model to be displayed in the floating card.
• presetLib: The library of presets for the sceneConfig.
• materialLib: The library of materials used in materialConfig and configuratorConfig .
• sceneConfig:
  • Environment: Path to the environment HDR file.
  • GemEnvironment: Path to the gem environment EXR file.
  • Ground: Path to the ground configuration JSON file.
  • Background : Path to the background image for the 3d scene.
• cameraConfig: Configuration for the camera settings.
• materialConfig: The materials that are going to be applied to the model on load
  • materials: An array of material objects, each with a name and a path to the material file.
  • type: The type of material configuration, typically MaterialPresetPlugin.
• configuratorConfig: An array of configurator option objects used in the material configurator ui, each with:
  • name: The name of the material layer in the 3d file.
  • title: The display title for the option.
  • options: An array of available options for this configurator, each with:
    • name: The name of the material or gem file.
    • type: The type of option, e.g., metal or gem.
• plugins:
  • SimpleBackgroundEnvUiPlugin2: Configuration for the background and environment UI plugin, including:
    • sceneEnvironmentRotation: Rotation of the environment.
    • sceneEnvironmentIntensity: Intensity of the environment lighting.
    • sceneEnvironmentFixedDirection: Boolean indicating if the environment direction is fixed.
    • tonemapBackground: Boolean indicating if background tonemapping is enabled.
    • tonemapGround: Boolean indicating if ground tonemapping is enabled.
    • type: The type of the plugin, typically SimpleBackgroundEnvUiPlugin2.
  • MaterialConfiguratorPlugin: Defines the materials available within the configurator UI.
    • type: Must be set to "MaterialConfiguratorPlugin".
    • resources: An object containing various resource such as materials and textures.
      • materials: A key-value store where each key is a unique identifier (UUID) for a material, and the value is an object defining the material's properties.
    • variations: An array of objects defining the structure and options presented in the configurator UI. Each object represents a layer of the model:
      • uuid: An identifier corresponding to the layer group (e.g., Metal01 Gem04).
      • title: The display name for this section in the UI (e.g., "Head", "Gemstone").
      • preview: Specifies how the options under this variation should be previewed (e.g., "color").
      • materials: An array listing the available material choices for this variation. Each item links to a material defined in resources.materials:
        • uuid: The UUID of the material from resources.materials.
        • resource: The type of resource, typically "materials".

TIP

The paths for the scene presets and materials can either be absolute URLs or relative to the basePath specified in your project configuration. This flexibility allows you to organize and reference your assets in a way that best fits your project structure.

Event Listener

The Viewer class emits custom events on window as it starts up:

Event	event.detail	Fired when
ijewel-viewer-ready	{ viewer }	The WebGi viewer is initialized. The project may still be loading.
ijewel-scene-ready	{ sceneReady: true }	The project configuration and scene have finished loading. Read configurator ring choices after this event.
ijewel-file-data	{ iJewelFileData }	A model loaded with loadModelById has had its Drive record resolved.

iJewelFileData is the Drive record for the file, not the 3D scene. Its config holds the settings saved on the file itself and defaultConfig the ones inherited from its folder; either can arrive as a JSON string, so parse defensively. This is how per-model settings such as tryonConfig reach your page - see Advanced Integration for a worked example.

Register both listeners before calling loadModelById, or you will miss them.

Example Usage

const project = {
  modelUrl: "https://example.com/model.glb",
  basePath: "https://example.com/assets/",
  logo: "https://example.com/logo.png",
  sceneConfig: { /* scene configuration */ },
  materialConfig: { /* material configuration */ },
  configuratorConfig: [/* configurator configuration */],
};

const viewerOptions = {
  showLogo: true,
  showCard: true,
  showSwitchNode: false,
  splitMaterialTabs: true,
  useIjewelLogo: false,
  hideQuality: true,
  logoScale: 1.5,
};

const viewer = new ijewelViewer.Viewer(document.getElementById("root"), project, viewerOptions);

// To update the project and the 3D model
viewer.render(newProject);

// Event listener for viewer ready event
window.addEventListener("ijewel-viewer-ready", async (ev) => {
  const viewer = ev.detail.viewer;
  // Additional actions to perform with the viewer instance

  //Example
  //set the max and min zoom for mobile and desktop 
  viewer.scene.activeCamera.addEventListener('update', (ev)=>{
      if(window.innerWidth < window.innerHeight){
        (viewer.scene.activeCamera.getControls()).minDistance = 14;
        (viewer.scene.activeCamera.getControls()).maxDistance = 9;

      }else{
        (viewer.scene.activeCamera.getControls()).maxDistance = 12;
        (viewer.scene.activeCamera.getControls()).minDistance = 7;
      }
  });
});