IafViewer

IafViewer overview

The IafViewer is a React component which enables a user to interact with a digital twin model in 3D space using various tools.

This page describes how to install and import the IafViewer component and describes the range of React data props available.

Note: For a general introduction to the IafViewer, refer to the IafViewer page in the Concepts section.

Install

npm install @invicara/iaf-viewer

Import

import { IafViewer } from "@invicara/iaf-viewer";

Props

Data props

Prop	Type	Description	Default value	Required
toolbarSize	String	Sets the size of the toolbar. Pass none, small, medium, or large.	medium	No
showToolTip	Boolean	Enables or disables the tool tip hover-over descriptions. Pass true or false.	true	No
sidePanelColor	String	Sets the side panel color. You can pass a hex code, RGB value, or a color name.	"#1D1D1D"	No
onHoverIconColor	String	Sets the icon color during a mouse hover event. You can pass a hex code, RGB value, or a color name.	invert(40%) sepia(86%) saturate(6224%) hue-rotate(311deg) brightness(83%) contrast(101%)	No
onActiveIconColor	String	Sets the color of the active icon. You can pass a hex code, RGB value, or a color name.	invert(40%) sepia(86%) saturate(6224%) hue-rotate(311deg) brightness(83%) contrast(101%)	No
toolbarColor	String	Sets the toolbar color. You can pass a hex code, RGB value, or a color name.	"#333333"	No
isShowNavCube	Boolean	Shows or hides the navigation cube. Pass true or false.	true	No
modelVersionId	String	Pass the model's version number as a string.		No
showNotification	Boolean	Show or hide notifications	true	No
enableFocusMode	Boolean	Enable or disable focus mode	true	No
enable2DViewer	Boolean	Toggles the display of the 2D viewer	true	No
enableOptimizedSelection	Boolean	Enables a performance-optimized algorithm that improves 2D and 3D node selection speed and prevents unnecessary rerendering	false	No
Workflow	String	Supports multiple animations, including animated GIFS, offers properties such as scale, rotation, and opacity to bring dynamic visuals to the interface. Allows you to specify an animation script and set the duration of a looping animation.	list: [ { uuid: 1, timeInSeconds: 4.5, loop: true, script: [] } ], active: undefined // change to desired UUID	No
modelComposition	String	Sets default visibility for specific model disciplines, ensuring critical components are consistently displayed. Using a JSON object of Boolean values, this enables you to specify which components are displayed from the building model, from a selection of: structural, architectural, mechanical, electrical, plumbing, fire protection and infrastructure.	initial: { Structural: false, Architectural: true, Mechanical: false, Electrical: false, Plumbing: false, FireProtection: false, Infrastructural: false, default: false }	No
enablePersistence	Boolean	Enables saving the IafViewer's current state to the database server. The IafViewer state could be set to Annotations, GIS data etc.	true	No
gis	Object	Enables GIS mode within the IafViewer, sets the Mapbox access token to use, and specifies a callback function which allows the application to interact with the map directly. If enabled, the viewer will overlay 3D models onto a Mapbox-powered GIS map at their configured geo-locations. It supports interactive GIS operations like pan, zoom, tilt, and orbit. Existing non-GIS features in earlier versions of IafViewer will continue to work as expected. For a breakdown of the object's props, see gis.	gis: { enabled: true, token: undefined, onIafMapReady: undefined}	No
enablePersistence	Boolean	Enables autosaving of IafViewer state to a remote database, such as annotations, GIS overlays, user-defined graphics, and view settings. When disabled, the viewer uses local browser session storage.	true	No
view3d	Object	Pass an object with your view3d configurations. For a breakdown of the object's props, see view3d.	{ opacity: 0.5, enable: true, displayMode: EvmUtils.EVMDisplayMode.SPLIT, showToolbar: true, alignment: EvmUtils.EVMWidgetAlignment.LEFT_BOTTOM}	No
view2d	Object	Pass an object with your view2d configurations. For a breakdown of the object's props, see view2d.	{ enable: true, fullscreen: false, displayMode: EvmUtils.EVMDisplayMode.DEFAULT, showToolbar: true, alignment: EvmUtils.EVMWidgetAlignment.LEFT_TOP }	No
arcgis	Object	Sets the configuration for the ArcGIS-based viewer inside IafViewer. Enables integration with ArcGIS 3D SceneView for rendering 3D models in geospatial context. Supports camera control, dynamic layers, feature slicing, event handling, and map readiness callbacks. For a breakdown of the object's props, see arcgis and arcgisOverview.		No
arcgisOverview	Object	Configures the ArcGIS Overview or Context View within the IafViewer. This mode is similar to the primary ArcGIS view but is designed as a top-down overview map, providing contextual navigation and control over the main ArcGIS mode. It can serve as a mini-map or secondary view for spatial orientation. When only one ArcGIS view mode is used in the IafViewer instance, either arcgis or arcgisOverview can fulfill the role, depending on use case preference. For a breakdown of the object's props, see arcgis and arcgisOverview.		No
ue	Object	Configures the Unreal Engine-based view within the IafViewer. Enables rendering of 3D content using Unreal Engine technology, supporting model interaction, zoom targeting, and event-driven behaviors.		No
photosphere	Object	Configures the Photosphere (360° Panoramic) view within the IafViewer. When enabled, this mode renders panoramic imagery or virtual environments, allowing users to explore scenes using rotation and zoom interaction.		No
title	String	A unique string label for identifying the viewer instance in logs and debugging.	undefined	No
toolbarSize	String	Sets the toolbar size. Enter small, medium, or large.	medium	No

Callback props

Prop	Event that triggers callback function	Returns
OnIsolateElementChangeCallback	The user isolates an element in the graphics viewer when they right-click the element, then click Isolate	The ID of the isolated element
OnSelectedElementChangeCallback	The user selects one or more elements in the graphics viewer	An updated array of the selected elements' IDs
OnResetCallback	The user clicks the Reset button	true
OnHiddenElementChangeCallback	The user hides one or more elements in the graphics viewer	An updated array of the hidden elements' IDs
saveSettings	The user clicks the Save & Close button in the Settings pane.	The IafViewer settings as a JSON object for your function to store in local storage.
OnNotificationCallback	An info, warning or error notification event occurs.	The notification as a JSON object
OnViewerReadyCallback	Callback function that triggers when the model's structure is successfully loaded and ready. This is called separately for 3D and 2D viewers. Pass '2d' or '3d' as the parameter.

Example

import React, {useEffect} from "react";import { IafViewer } from "@invicara/iaf-viewer";
const ViewerPage = () => {
  const mySaveSettingsFunction = (settings) => {    //your function here  }
  return (    <PageTemplate>      <IafViewer         toolbarSize={"large"}        saveSettings={mySaveSettingsFunction}      />    </PageTemplate>  )}
export default ViewerPage;

Object prop breakdowns

View3d

Prop	Type	Description	Default value	Required
view3d.opacity	Number	Set the 3D model's opacity between fully transparent at 0.0 to fully opaque at 1.0.	1.0	No
view3d.enable	Boolean	Enables or disables the 3D model rendering.	true	No
view3d.displayMode	System variable	Defines how the 3D viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	EvmUtils.EVMDisplayMode.FULLSCREEN	No
view3d.showToolbar	Boolean	Shows or hides the 3D viewer toolbar	false	No
view3d.alignment	System variable	Specify the viewer alignment within its container or fixed space using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	EvmUtils.EVMWidgetAlignment.RIGHT_TOP	No

View2d

Prop	Type	Description	Default value	Required
enable	Boolean	Enables or disables the 2D viewer.	true	No
fullscreen	Boolean	Sets to true to make the 2D viewer occupy the full screen.	true	No
displayMode	System variable	Defines how the 2D viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	EvmUtils.EVMDisplayMode.DEFAULT	No
showToolbar	Boolean	Display or hide the 2D viewer's toolbar.	true	No
alignment	System variable	Determines the alignment of the viewer when using display modes like SPLIT or FIXED using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	EvmUtils.EVMWidgetAlignment.LEFT_TOP	No

GIS

GIS features rely on external GIS services like Mapbox. Applications integrating GIS must:

• Supply a valid Mapbox token (token)
• Handle token lifecycle (generation, refresh, expiration)
• Ensure compliance with Mapbox’s licensing, usage limits, and terms of service.

Prop	Type	Description	Default value	Required
enable	Boolean	Enables or disables GIS mode.	false	No
token	String	The Mapbox access token to use for GIS map initialization. This token must be a valid temporary or permanent token generated by the hosting application using its own Mapbox account and license. The viewer does not handle token generation or renewal internally. Token expiry, scope, and lifecycle must be managed by the application.	undefined	No
opacity	Boolean	Set the GIS map layer's opacity between fully transparent at 0.0 to fully opaque at 1.0.	1.0	No
onIafMapReady	Boolean	A callback function triggered when the GIS map (Mapbox instance) is fully initialized. It provides a monitored proxy to the underlying Mapbox GL JS instance, allowing the application to interact with the map directly and customize GIS behavior. Typical operations within this callback: Add custom map layers Modify map style Add navigation controls Attach GIS-specific event handlers	undefined	No
displayMode	System variable	Defines how the GIS viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	EvmUtils.EVMDisplayMode.FULLSCREEN	No
showToolbar	Boolean	Controls the toolbar visibility in GIS mode.	false	No
alignment	System variable	Determines the alignment of the GIS viewer panel when using display modes like SPLIT or FIXED using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	EvmUtils.EVMWidgetAlignment.RIGHT_TOP	No

Arcgis and arcgis overview

Prop	Type	Description	Default value	Required
enable	Boolean	Enables or disables the ArcGIS view.	false	No
slicedElements	Array	List of model elements to slice or clip within the scene.	false	No
themeElements	Array	Elements with visual themes or highlighting applied.	[]	No
layers	Array	ArcGIS layers to render in the viewer for example basemaps, terrain, overlays.	[]	No
graphics	Array	Array of graphic overlays, for example points, lines, polygons.	[]	No
zoomElements	Array	List of element IDs or references to zoom into on initialization.	[]	No
camera	Object	Initial or current camera configuration such as position, tilt, and heading.	{}	No
config	Object	Additional ArcGIS viewer configuration for example API keys, options.	false	No
portalUrl	String	ArcGIS portal URL for example, "https://gis.hlplanning.com/arcgis".	undefined	No
apiKey	String	ArcGIS portal API key	undefined	No
model	String	Web scene ID to load for example, "6745f5a0f1df4812a26925c19fdab6f8".	undefined	No
sceneWKID	String	Spatial reference WKID for the scene for example, 102100.	undefined	No
command	Array	Legacy property for compatibility with earlier command-based configurations.	[]	No
eventHandler	Function	Callback for handling interaction and system events from the ArcGIS viewer.	undefined	No
onIafMapReady	Function (mapInstance: __ArcGISMapView__) => void	Callback invoked when the ArcGIS map instance is fully initialized. Provides access to the MapView or SceneView instance.	undefined	No
displayMode	System variable	Defines how the ArcGIS viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	arcgis: EvmUtils.EVMDisplayMode.FULLSCREEN, arcgisOverview: EvmUtils.EVMDisplayMode.DEFAULT	No
showToolbar	Boolean	Controls the ArcGIS toolbar visibility.	true	No
alignment	System variable	Determines the alignment of the GIS viewer panel when using display modes like SPLIT or FIXED using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	arcgis: EvmUtils.EVMWidgetAlignment.LEFT_TOP, arcgisOverview: EvmUtils.EVMWidgetAlignment.LEFT_BOTTOM	No

  arcgis={{    enable: true,    slicedElements: ['zone-12'],    themeElements: ['sensor-critical'],    layers: ['base-terrain', 'heatmap-layer'],    graphics: [customLine, customPoint],    zoomElements: ['facility-23'],    camera: { heading: 45, tilt: 30 },    config: {       // required...      portalUrl: "https://gis.hlplanning.com/arcgis", // gis server      apiKey:    `AAPK6c81d14b0cea426f81fa5b6abb9aa0dfGZFEkccrQXsiqRmnLr1Lpk6Khj1H4cNisCMVfDH_x313UuFSGDinndbc3hr7fqVu`, // api key for above server      model:     "6745f5a0f1df4812a26925c19fdab6f8", // web scene id      sceneWKID: 102100,      // optional...      shadows: false,      groundOpacity: 1,      popUpEnabled: false,           // use GIS built in popups?      highlightOnClick: false,       // use GIS built in highlighting of elements?      highlightTheme: {        color: [255, 255, 0, 1],        haloColor: "white",        haloOpacity: 0.9,        fillOpacity: 0.2,        shadowColor: "black",        shadowOpacity: 0.5      },      // Camera position coordinates (and coordinates sent to the MMV command) are dependent on the model's coord system      // It is up to the controlling app (this app) to convert between model coordinate systems      initialCameraPosition: INITIAL_POSITION_CAMERA,      hiddenLayers: [        GIS_LAYER_NAMES.BUILDINGS_LABEL_POINTS,        GIS_LAYER_NAMES.DISTRICTS_LABEL_POINTS      ],      layerInfo: GIS_LAYERS                    },    command: [],    displayMode: EvmUtils.EVMDisplayMode.SPLIT,    showToolbar: true,    alignment: EvmUtils.EVMWidgetAlignment.RIGHT_BOTTOM,    eventHandler: (event) => {      console.log('ArcGIS event:', event);    },    onIafMapReady: (mapInstance) => {      mapInstance.setMapStyle("arcgis/light-gray");    }  }}

UE

Prop	Type	Description	Default value	Required
enable	Boolean	Enables or disables the Unreal Engine viewer.	false	No
config	Object	Configuration object passed to the Unreal Engine runtime.Used for setting rendering options, feature toggles, or initialization parameters.	false	No
zoomElements	Array	List of element IDs or references to focus on when initializing the view.	[]	No
command	Array	Legacy property for compatibility with command-driven configurations.	false	No
eventHandler	Function	Callback function to handle Unreal Engine viewer events. Used to react to user actions or system events such as selecting an object or changing a view.	undefined	No
displayMode	System variable	Defines how the Unreal Engine viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	arcgis: EvmUtils.EVMDisplayMode.FULLSCREEN, arcgisOverview: EvmUtils.EVMDisplayMode.DEFAULT	No
showToolbar	Boolean	Controls the Unreal Engine toolbar visibility.	true	No
alignment	System variable	Determines the alignment of the GIS viewer panel when using display modes like SPLIT or FIXED using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	arcgis: EvmUtils.EVMWidgetAlignment.RIGHT_BOTTOM, arcgisOverview: EvmUtils.EVMWidgetAlignment.LEFT_BOTTOM	No

  ue={{    enable: true,    config: {      environment: 'industrial',      quality: 'ultra'    },    zoomElements: ['machine-42'],    command: [],    displayMode: EvmUtils.EVMDisplayMode.FULLSCREEN,    showToolbar: false,    alignment: EvmUtils.EVMWidgetAlignment.LEFT_TOP,    eventHandler: (event) => {      console.log('Unreal Engine event:', event);    }  }}

Photosphere

Prop	Type	Description	Default value	Required
enable	Boolean	Enables or disables the Photosphere view.	false	No
config	Object	Configuration object for the Photosphere renderer, such as the image URL, viewer parameters, and initial orientation.	{}	No
displayMode	System variable	Defines how the Photosphere viewer is displayed within the application layout using one of the following options from EvmUtils.EVMDisplayMode: DEFAULT: Standard embedded mode in the layout SPLIT: Viewer shares space side-by-side with another panel FULLSCREEN: Viewer takes up the entire available viewport FIXED: Viewer is placed in a fixed area of the screen.	arcgis: EvmUtils.EVMDisplayMode.FULLSCREEN, arcgisOverview: EvmUtils.EVMDisplayMode.DEFAULT	No
showToolbar	Boolean	Controls the Photosphere toolbar visibility.	true	No
alignment	System variable	Determines the alignment of the Photosphere viewer's panel when using display modes like SPLIT or FIXED using one of the following options from EvmUtils.EVMWidgetAlignment: LEFT_TOP, LEFT_BOTTOM, RIGHT_TOP, RIGHT_BOTTOM.	arcgis: EvmUtils.EVMWidgetAlignment.RIGHT_BOTTOM, arcgisOverview: EvmUtils.EVMWidgetAlignment.RIGHT_TOP	No

photosphere={{  enable: true,  config: {    imageUrl: 'https://example.com/panorama.jpg',    initialYaw: 180  },  displayMode: EvmUtils.EVMDisplayMode.FULLSCREEN,  showToolbar: true,  alignment: EvmUtils.EVMWidgetAlignment.LEFT_BOTTOM}}