Attributes of the Needle Engine Web Component

Needle Engine is available as a web component: <needle-engine>. This component can be used to load and display 3D scenes, models, and more in a web browser. It comes with a set of attributes that allow you to configure its behavior, look and feel. All those settings can be overwritten by code, but the attributes are a convenient way to set them up in HTML.

::: tip The web component is in index.html Whether creating a project via Unity or Blender, or directly in code, you can use and adjust the <needle-engine> web component. Usually, you will find it in the index.html file of your web project. :::

The table below shows a list of available attributes and their descriptions.

Attribute	Description
Loading
src	Path to one or multiple glTF or glb files. Supported types are string, string[] or a stringified array (, separated)
Loading Display	Available options to change how the Needle Engine loading display looks. Use localhost:3000?debugloadingrendering for easier editing
loading-blur	Optional: Blur the scene until LODs are loaded (if any). Default: disabled
poster	Optional: Set the poster attribute to show a placeholder image while loading. Example: <needle-engine poster="https://yourdomain.com/poster.png">. By just using the attribute without a url the poster in include/poster.webp will be used if it exists (e.g. <needle-engine poster>)
loading-background	PRO — Default: transparent. Change the loading background color (e.g. #dd5500)
hide-loading-overlay	PRO — Do not show the loading overlay
loading-logo-src	PRO — Removed in Needle Engine 4.10.0 - Change the loading logo image (e.g. https://yourdomain.com/logo.png or /logo.png)
Events
loadstart	Name of the function to call when loading starts. Note that the arguments are (ctx:Context, evt:Event). You can call evt.preventDefault() to hide the default loading overlay
progress	Name of the function to call when loading updates. onProgress(ctx:Context, evt: {detail: {context:Context, name:string, index:number, count:number, totalProgress01:number, progress:ProgressEvent}) { ... }
loadfinished	Name of the function to call when loading finishes
Rendering
background-color	optional, hex color to be used as a background color. Examples: rgb(255, 200, 100), #dddd00
background-image	optional, URL to a skybox image (background image) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar. Supports FastHDR
background-blurriness	optional, bluriness value between 0 (no blur) and 1 (max blur) for the background-image. Example: background-blurriness="0.5"
environment-image	optional, URL to a environment image (environment light) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar. Supports FastHDR
contactshadows	optional, render contact shadows
tone-mapping	optional, supported values are none, linear, neutral, agx
tone-mapping-exposure	optional number e.g. increase exposure with tone-mapping-exposure="1.5", requires tone-mapping to be set
Interaction
autoplay	add or set to true to auto play animations e.g. <needle-engine autoplay
camera-controls	add or set to true to automatically add OrbitControls if no camera controls are found in the scene
auto-rotate	add to enable auto-rotate (only used with camera-controls)
Advanced	Available options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing
dracoDecoderPath	URL to the draco decoder e.g. ./include/draco/ to use the local Draco decoder
dracoDecoderType	draco decoder type. Options are wasm or js. See three.js documentation
ktx2DecoderPath	URL to the KTX2 decoder e.g. ./include/ktx2/ to use the local KTX2 decoder
HTML	Options to access HTML elements
focus-rect	Query string to select an HTML element on your website to be used as the camera-focus-rect - Demo. Note that you can also set it programmatically with ctx.setCameraFocusRect(<element>|DOMRect)
Internal
hash	Used internally, is appended to the files being loaded to force an update (e.g. when the browser has cached a glb file). Should not be edited manually.

Upgrade notice:

• Removed attributes in Needle Engine 4.5.0: loading-style, loading-background-color, loading-text-color, primary-color, secondary-color

• Remove attributes in Needle Engine 4.10.0: loading-logo-src

Examples

<!-- Setting the path to a custom glb to be loaded -->
<needle-engine src="path/to/your.glb"></needle-engine>

<!-- Overriding where the draco decoder is located -->
<needle-engine src="path/to/your.glb" dracoDecoderPath="./include/draco/"></needle-engine>

Setting environment images, playing animation and automatic camera controls. See it live on stackblitz

<needle-engine
      camera-controls
      auto-rotate
      autoplay
      skybox-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      environment-image="https://dl.polyhaven.org/file/ph-assets/HDRIs/hdr/1k/industrial_sunset_puresky_1k.hdr"
      src="https://raw.githubusercontent.com/KhronosGroup/glTF-Sample-Models/master/2.0/DamagedHelmet/glTF-Embedded/DamagedHelmet.gltf"
      >
      </needle-engine>

Receiving loading events:

<needle-engine progress="onProgress" loadfinished="onLoadFinished"> </needle-engine>
<script>
    function onProgress(ctx, event) {
        const progress01 = evt.detail.totalProgress01;
        console.log(progress01);
    }

    function onLoadFinished() {
        console.log("Needle Engine has finished loading");
    }
</script>

:::tip Need more control? For further customization or callbacks see the scripting documentation or Needle Engine hooks. Needle Engine is fully scriptable. :::

:::tip Prefer working visually? Needle Engine can also be used with Editors like Unity or Blender. :::