.. role:: clio-optional
   :class: clio-flag clio-flag-optional

.. role:: clio-static
   :class: clio-flag clio-flag-static


##################
WebViewerComponent
##################

.. js:class:: wvc.WebViewerComponent

   A simple HTML tag to quickly initialize a complete viewer.
   
   This component provides a full-featured 3D model viewer with support for loading models, navigation, selection, markup, and various visualization modes.
   
   .. rubric:: Examples
   
   
   .. code-block:: html
   
      <hoops-web-viewer endpointuri="/models/sample.scs" enginepath="/engine">
      </hoops-web-viewer>
      
      <script>
        const viewer = document.getElementsByTagName('hoops-web-viewer')[0];
        viewer.addEventListener('hwvReady', (event) => {
          console.log('Viewer ready:', event.detail);
        });
      </script>
   
   .. rubric:: Custom Element
   
   
   ``hoops-web-viewer``
   
   .. rubric:: Attributes
   
   
   **endpointuri**
   
   
      Specifies the endpoint to be used by the viewer.
   
   
   **model**
   
   
      Specifies the instance name to be loaded.
   
   
   **sessiontoken**
   
   
      An arbitrary value used for authentication.
   
   
   **renderertype**
   
   
      Specifies the renderer type to be used.
   
   
   **empty**
   
   
      Whether the viewer should be started without connecting to a server or loading a model.
   
   
   **usepointerevents**
   
   
      Specifies whether pointer events should be used when available.
   
   
   **streamingmode**
   
   
      Sets the streaming mode that the viewer will use.
   
   
   **memorylimit**
   
   
      Controls the amount of mesh data present on the client machine at given time.
   
   
   **boundingpreviewmode**
   
   
      Specifies what types of bounding previews should be rendered.
   
   
   **defaultmeshlevel**
   
   
      Specifies which mesh detail level will be used to initially stream the model.
   
   
   **streamcutoffscale**
   
   
      Specifies a scale factor that will be applied to the streaming size cutoff.
   
   
   **disableautomaticbackgroundsheets**
   
   
      If true, then automatic generation of background sheets for drawings is not performed when the drawing is loaded.
   
   
   **disableautomaticfloorplanoverlay**
   
   
      If true, then the floorplan overlay capability will not be displayed automatically for BIM enabled models.
   
   
   **calculatedefaultviewaxes**
   
   
      If true, the default view axes will be calculated from the initial camera unless explicitly set during authoring time.
   
   
   **disableautomaticfitworld**
   
   
      If true, disable automatic fitworld on camera activation when there is no camera on view.
   
   
   **enableshatteredmodeluiviews**
   
   
      If true, then CAD views contained within external models will populate the model tree UI.
   
   
   **enginepath**
   
   
      Path containing the graphics engine ``.wasm`` files.
   
   
   **defaultmetallicfactor**
   
   
      Sets a default metallic factor that will be applied to ALL non PBR materials in the scene.
   
   
   **defaultroughnessfactor**
   
   
      Sets a default roughness factor that will be applied to ALL non PBR materials in the scene.
   
   
   .. rubric:: Events
   
   
   **hwvAddCuttingSection**
   
   
      Emitted when a cutting section is added
   
   
   **hwvAssemblyTreeReady**
   
   
      Emitted when the assembly tree is ready
   
   
   **hwvBcfLoaded**
   
   
      Emitted when a BCF file is loaded
   
   
   **hwvBcfRemoved**
   
   
      Emitted when a BCF file is removed
   
   
   **hwvBeginInteraction**
   
   
      Emitted when user interaction begins
   
   
   **hwvCadViewCreated**
   
   
      Emitted when a CAD view is created
   
   
   **hwvCamera**
   
   
      Emitted when camera position changes
   
   
   **hwvCappingIdle**
   
   
      Emitted when capping becomes idle
   
   
   **hwvConfigurationActivated**
   
   
      Emitted when a configuration is activated
   
   
   **hwvContextMenu**
   
   
      Emitted when context menu is requested
   
   
   **hwvCuttingPlaneDrag**
   
   
      Emitted during cutting plane drag
   
   
   **hwvCuttingPlaneDragEnd**
   
   
      Emitted when cutting plane drag ends
   
   
   **hwvCuttingPlaneDragStart**
   
   
      Emitted when cutting plane drag starts
   
   
   **hwvCuttingSectionsLoaded**
   
   
      Emitted when cutting sections are loaded
   
   
   **hwvEndInteraction**
   
   
      Emitted when user interaction ends
   
   
   **hwvExplode**
   
   
      Emitted when explode state changes
   
   
   **hwvFirstModelLoaded**
   
   
      Emitted when the first model is loaded
   
   
   **hwvFrameDrawn**
   
   
      Emitted when a frame is drawn
   
   
   **hwvHandleEvent**
   
   
      Emitted during a handle event
   
   
   **hwvHandleEventEnd**
   
   
      Emitted when a handle event ends
   
   
   **hwvHandleEventStart**
   
   
      Emitted when a handle event starts
   
   
   **hwvHwfParseComplete**
   
   
      Emitted when HWF parsing is complete
   
   
   **hwvIncrementalSelectionBatchBegin**
   
   
      Emitted when incremental selection batch begins
   
   
   **hwvIncrementalSelectionBatchEnd**
   
   
      Emitted when incremental selection batch ends
   
   
   **hwvIncrementalSelectionEnd**
   
   
      Emitted when incremental selection ends
   
   
   **hwvInfo**
   
   
      Emitted with informational messages
   
   
   **hwvLineCreated**
   
   
      Emitted when a line markup is created
   
   
   **hwvLineDeleted**
   
   
      Emitted when a line markup is deleted
   
   
   **hwvLineLoaded**
   
   
      Emitted when a line markup is loaded
   
   
   **hwvMeasurementBegin**
   
   
      Emitted when measurement begins
   
   
   **hwvMeasurementCreated**
   
   
      Emitted when a measurement is created
   
   
   **hwvMeasurementDeleted**
   
   
      Emitted when a measurement is deleted
   
   
   **hwvMeasurementHidden**
   
   
      Emitted when a measurement is hidden
   
   
   **hwvMeasurementLoaded**
   
   
      Emitted when a measurement is loaded
   
   
   **hwvMeasurementShown**
   
   
      Emitted when a measurement is shown
   
   
   **hwvMeasurementValueSet**
   
   
      Emitted when a measurement value is set
   
   
   **hwvMissingModel**
   
   
      Emitted when a model is missing
   
   
   **hwvModelLoadBegin**
   
   
      Emitted when model loading begins
   
   
   **hwvModelLoadFailure**
   
   
      Emitted when model loading fails
   
   
   **hwvModelStructureHeaderParsed**
   
   
      Emitted when model structure header is parsed
   
   
   **hwvModelStructureReady**
   
   
      Emitted when the model structure is loaded
   
   
   **hwvModelSwitched**
   
   
      Emitted when the model is switched
   
   
   **hwvModelSwitchStart**
   
   
      Emitted when model switching starts
   
   
   **hwvNoteTextCreated**
   
   
      Emitted when a note text is created
   
   
   **hwvNoteTextDeleted**
   
   
      Emitted when a note text is deleted
   
   
   **hwvNoteTextHidden**
   
   
      Emitted when a note text is hidden
   
   
   **hwvNoteTextShown**
   
   
      Emitted when a note text is shown
   
   
   **hwvNoteTextUpdated**
   
   
      Emitted when a note text is updated
   
   
   **hwvOverlayViewportSet**
   
   
      Emitted when overlay viewport is set
   
   
   **hwvReady**
   
   
      Emitted when the web viewer is initialized and ready
   
   
   **hwvRedlineCreated**
   
   
      Emitted when a redline is created
   
   
   **hwvRedlineDeleted**
   
   
      Emitted when a redline is deleted
   
   
   **hwvRedlineUpdated**
   
   
      Emitted when a redline is updated
   
   
   **hwvRemoveCuttingSection**
   
   
      Emitted when a cutting section is removed
   
   
   **hwvSceneReady**
   
   
      Emitted when the scene is ready
   
   
   **hwvSelectionArray**
   
   
      Emitted when selection changes
   
   
   **hwvSheetActivated**
   
   
      Emitted when a sheet is activated
   
   
   **hwvSheetDeactivated**
   
   
      Emitted when a sheet is deactivated
   
   
   **hwvStreamingActivated**
   
   
      Emitted when streaming is activated
   
   
   **hwvStreamingDeactivated**
   
   
      Emitted when streaming is deactivated
   
   
   **hwvSubtreeDeleted**
   
   
      Emitted when a subtree is deleted
   
   
   **hwvSubtreeLoaded**
   
   
      Emitted when a subtree is loaded
   
   
   **hwvTimeout**
   
   
      Emitted on session timeout
   
   
   **hwvTimeoutWarning**
   
   
      Emitted before session timeout
   
   
   **hwvTransitionBegin**
   
   
      Emitted when a transition begins
   
   
   **hwvTransitionEnd**
   
   
      Emitted when a transition ends
   
   
   **hwvViewAxes**
   
   
      Emitted when view axes change
   
   
   **hwvViewCreated**
   
   
      Emitted when a view is created
   
   
   **hwvViewDeactivated**
   
   
      Emitted when a view is deactivated
   
   
   **hwvViewDeleted**
   
   
      Emitted when a view is deleted
   
   
   **hwvViewLoaded**
   
   
      Emitted when a view is loaded
   
   
   **hwvViewOrientation**
   
   
      Emitted when view orientation changes
   
   
   **hwvVisibilityChanged**
   
   
      Emitted when visibility changes
   
   
   **hwvWalkOperatorActivated**
   
   
      Emitted when walk operator is activated
   
   
   **hwvWalkOperatorDeactivated**
   
   
      Emitted when walk operator is deactivated
   
   
   **hwvWebGlContextLost**
   
   
      Emitted when WebGL context is lost
   
   
   **hwvWebsocketConnectionClosed**
   
   
      Emitted when websocket connection closes
   
   
   **hwvXHRonerror**
   
   
      Emitted on XHR error
   
   
   **hwvXHRonloadend**
   
   
      Emitted when XHR load ends
   
   
   **hwvXHRonprogress**
   
   
      Emitted on XHR progress
   
   
   .. rubric:: Since
   
   
   ``2025.8.0``
   
   
   Index
   =====
   
   .. rubric:: Properties
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:data:`~wvc.WebViewerComponent.styles`
   * :js:data:`~wvc.WebViewerComponent.calculateDefaultViewAxes`
   * :js:data:`~wvc.WebViewerComponent.container`
   * :js:data:`~wvc.WebViewerComponent.disableAutomaticBackgroundSheets`
   * :js:data:`~wvc.WebViewerComponent.disableAutomaticFitWorld`
   * :js:data:`~wvc.WebViewerComponent.disableAutomaticFloorplanOverlay`
   * :js:data:`~wvc.WebViewerComponent.empty`
   * :js:data:`~wvc.WebViewerComponent.enableShatteredModelUiViews`
   * :js:data:`~wvc.WebViewerComponent.usePointerEvents`
   * :js:data:`~wvc.WebViewerComponent.boundingPreviewMode`
   * :js:data:`~wvc.WebViewerComponent.contextManager`
   * :js:data:`~wvc.WebViewerComponent.defaultMeshLevel`
   * :js:data:`~wvc.WebViewerComponent.defaultMetallicFactor`
   * :js:data:`~wvc.WebViewerComponent.defaultRoughnessFactor`
   * :js:data:`~wvc.WebViewerComponent.endpointUri`
   * :js:data:`~wvc.WebViewerComponent.enginePath`
   * :js:data:`~wvc.WebViewerComponent.memoryLimit`
   * :js:data:`~wvc.WebViewerComponent.model`
   * :js:data:`~wvc.WebViewerComponent.rendererType`
   * :js:data:`~wvc.WebViewerComponent.sessionToken`
   * :js:data:`~wvc.WebViewerComponent.streamCutoffScale`
   * :js:data:`~wvc.WebViewerComponent.streamingMode`
   
   .. rubric:: Accessors
   
   
   .. rst-class:: api-xref-list
   
   
   * :js:func:`~wvc.WebViewerComponent.viewer`
   
   



.. rst-class:: kind-group kind-properties

.. rubric:: Properties
   :class: kind-group-title


.. js:data:: wvc.WebViewerComponent.styles

      .. rst-class:: clio-flags
      
         :clio-static:`static`
      
      .. rst-class:: sig-pretty-signature
      
         | styles: *CSSResult*\ []
      
      Array of styles to apply to the element. The styles should be defined using the ``css`` tag function, via constructible stylesheets, or imported from native CSS module scripts.
      
      Note on Content Security Policy:
      
      Element styles are implemented with ``<style>`` tags when the browser doesn't support adopted StyleSheets. To use such ``<style>`` tags with the style-src CSP directive, the style-src value must either include 'unsafe-inline' or ``nonce-<base64-value>`` with ``<base64-value>`` replaced be a server-generated nonce.
      
      To provide a nonce to use on generated ``<style>`` elements, set ``window.litNonce`` to a server-generated nonce in your page's HTML, before loading application code:
      
      .. code-block:: html
      
         <script>
           // Generated and unique per request:
           window.litNonce = 'a1b2c3d4';
         </script>
      



.. js:data:: wvc.WebViewerComponent.calculateDefaultViewAxes

      .. rst-class:: sig-pretty-signature
      
         | calculateDefaultViewAxes: *boolean*
      
      If true, the default view axes will be calculated from the initial camera unless explicitly set during authoring time.
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.container

      .. rst-class:: sig-pretty-signature
      
         | container: *HTMLElement*
      
      The DOM container element that hosts the WebViewer canvas. Automatically assigned during component initialization.
      



.. js:data:: wvc.WebViewerComponent.disableAutomaticBackgroundSheets

      .. rst-class:: sig-pretty-signature
      
         | disableAutomaticBackgroundSheets: *boolean*
      
      If true, then automatic generation of background sheets for drawings is not performed when the drawing is loaded.
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.disableAutomaticFitWorld

      .. rst-class:: sig-pretty-signature
      
         | disableAutomaticFitWorld: *boolean*
      
      If true, disable automatic fitworld on camera activation when there is no camera on view
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.disableAutomaticFloorplanOverlay

      .. rst-class:: sig-pretty-signature
      
         | disableAutomaticFloorplanOverlay: *boolean*
      
      If true, then the floorplan overlay capability will not be displayed automatically for BIM enabled models
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.empty

      .. rst-class:: sig-pretty-signature
      
         | empty: *boolean*
      
      Whether the viewer should be started without connecting to a server or loading a model.
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.enableShatteredModelUiViews

      .. rst-class:: sig-pretty-signature
      
         | enableShatteredModelUiViews: *boolean*
      
      If true, then CAD views contained within external models will populate the model tree UI.
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.usePointerEvents

      .. rst-class:: sig-pretty-signature
      
         | usePointerEvents: *boolean*
      
      Specifies whether pointer events should be used when available. Setting this option to false can be useful when using web views in GUI toolkits that rely on Internet Explorer.
      
      .. rubric:: Default
      
      
      `````ts
      false
      `````
      



.. js:data:: wvc.WebViewerComponent.boundingPreviewMode

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | boundingPreviewMode: *BoundingPreviewMode*
      
      Specifies what types of bounding previews should be rendered. Any invalid value will be converted to ``StreamingMode.Default``\ .
      



.. js:data:: wvc.WebViewerComponent.contextManager

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | contextManager: :js:class:`WebViewerContextManager <wvc.WebViewerContextManager>`
      
      Context manager for coordinating component communication. Automatically injected when the component is within a context manager.
      



.. js:data:: wvc.WebViewerComponent.defaultMeshLevel

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | defaultMeshLevel: *number*
      
      Specifies which mesh detail level will be used to initially stream the model.
      



.. js:data:: wvc.WebViewerComponent.defaultMetallicFactor

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | defaultMetallicFactor: *number*
      
      Sets a default metallic factor that will be applied to ALL non PBR materials in the scene. Acceptable value range is (0.0 - 1.0) If [[defaultRoughnessFactor]] is specified and this value is omitted, a value of 1.0 will be assumed.
      



.. js:data:: wvc.WebViewerComponent.defaultRoughnessFactor

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | defaultRoughnessFactor: *number*
      
      Sets a default roughness factor that will be applied to ALL non PBR materials in the scene. . Acceptable value range is (0.0 - 1.0) If [[defaultMetallicFactor]] is specified and this value is omitted, a value of 1.0 will be assumed.
      



.. js:data:: wvc.WebViewerComponent.endpointUri

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | endpointUri: *string*
      
      Specifies the endpoint to be used by the viewer. This can be of type: http, https or ws.
      



.. js:data:: wvc.WebViewerComponent.enginePath

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | enginePath: *string*
      
      Path containing the graphics engine ``.wasm`` files. Follows the same rules as the ``src`` attribute of an HTML ``script`` tag.
      



.. js:data:: wvc.WebViewerComponent.memoryLimit

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | memoryLimit: *number*
      
      Controls the amount of mesh data present on the client machine at given time. This value is expressed in `Mebibytes <https://en.wikipedia.org/wiki/Mebibyte>`__\ .
      



.. js:data:: wvc.WebViewerComponent.model

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | model: *string*
      
      Specifies the instance name to be loaded. This option is required if you specify an enpdointUri of type ``ws://`` or ``wss://``\ .
      



.. js:data:: wvc.WebViewerComponent.rendererType

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | rendererType: *RendererType*
      
      Specifies the renderer type to be used. Any invalid value will be converted to ``RendererType.Client``\ .
      



.. js:data:: wvc.WebViewerComponent.sessionToken

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | sessionToken: *string*
      
      An arbitrary value used for authentication. If used, it must match the token expected by the server for connection to proceed.
      



.. js:data:: wvc.WebViewerComponent.streamCutoffScale

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | streamCutoffScale: *number*
      
      Specifies a scale factor that will be applied to the streaming size cutoff.
      
      In streaming sessions, an object whose projected size is lower than the cutoff will not be streamed until its projected size reaches the cutoff.
      
      In file sessions, when loading a tree via XML, a file whose projected size is lower than the cutoff will not be requested until its projected size reaches the cutoff.
      
      A value of 0 will disable the cutoff.  The value should be in the interval of [0.0, 2.0]. If unspecified, this value will default to 1.0 for streaming sessions and 0.0 (disabled) for file based sessions.
      



.. js:data:: wvc.WebViewerComponent.streamingMode

      .. rst-class:: clio-flags
      
         :clio-optional:`optional`
      
      .. rst-class:: sig-pretty-signature
      
         | streamingMode: *StreamingMode*
      
      Sets the streaming mode that the viewer will use. Any invalid value will be converted to ``StreamingMode.Default``\ .
      



.. rst-class:: kind-group kind-accessors

.. rubric:: Accessors
   :class: kind-group-title


.. js:method:: wvc.WebViewerComponent.viewer

      .. rst-class:: sig-pretty-signature
      
         | *get* viewer(): (*None* | *WebViewer*\ )
      
      Gets the underlying WebViewer instance. Provides access to the full HOOPS Web Viewer API for advanced operations.
      
      **Returns**\ : (*None* \| *WebViewer*\ )
      
      
         The WebViewer instance or null if not initialized
      
      




