Needle Engine Documentation
Downloads
  • What is Needle Engine?
  • Testimonials
  • Get an overview

    • Samples and Showcase
    • Our Vision 🔮
    • Feature Overview
    • Technical Overview
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine for Unity
    • Needle Engine for Blender
    • Needle Engine as Web Component
    • Needle Engine on your Website
    • Needle Cloud
  • Core Concepts

    • Structure of a Needle Engine project
    • Everywhere Actions
    • Exporting Assets to glTF
    • Frameworks, Bundlers, HTML
    • Testing on local devices
    • Deployment and Optimization
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Networking
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • How To Debug
    • Questions and Answers (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Scripting in Needle Engine
    • Scripting Introduction for Unity Developers
    • Needle Core Components
    • Everywhere Actions
  • Components and Lifecycle

    • Creating and using Components
    • @serializable and other decorators
    • Automatic Component Generation
    • Scripting Examples
    • Community Contributions
    • Additional Modules
  • Settings and APIs

    • <needle-engine> Configuration
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
Downloads
  • What is Needle Engine?
  • Testimonials
  • Get an overview

    • Samples and Showcase
    • Our Vision 🔮
    • Feature Overview
    • Technical Overview
  • Resources

    • Pricing and Plans
    • Changelog
    • API Documentation
    • Support & Community
  • Integrations

    • Needle Engine for Unity
    • Needle Engine for Blender
    • Needle Engine as Web Component
    • Needle Engine on your Website
    • Needle Cloud
  • Core Concepts

    • Structure of a Needle Engine project
    • Everywhere Actions
    • Exporting Assets to glTF
    • Frameworks, Bundlers, HTML
    • Testing on local devices
    • Deployment and Optimization
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Networking
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • How To Debug
    • Questions and Answers (FAQ) 💡
    • Support and Community
  • Videos

    • Tutorials on Youtube
    • Interviews on Youtube
  • Scripting Overview

    • Scripting in Needle Engine
    • Scripting Introduction for Unity Developers
    • Needle Core Components
    • Everywhere Actions
  • Components and Lifecycle

    • Creating and using Components
    • @serializable and other decorators
    • Automatic Component Generation
    • Scripting Examples
    • Community Contributions
    • Additional Modules
  • Settings and APIs

    • <needle-engine> Configuration
    • needle.config.json
    • Needle Engine API
    • three.js API
Help
Samples
Pricing
  • Needle Website
  • Needle Cloud
  • Support Community
  • Discord Server
  • X/Twitter
  • YouTube
  • Newsletter
  • Email
  • Feedback
  • Github
  • English
  • 简体中文
  • Español
  • Português
  • Français
  • हिन्दी
  • 日本語
  • Deutsch
  • Tiếng Việt
  • Getting Started

    • Downloads
    • Needle Engine for Unity
    • Needle Engine for Blender
    • Needle Engine as Web Component
    • Needle Engine on your Website
    • Needle Cloud
    • Custom integrations
    • Support and Community
  • Core Concepts

    • Structure of a Needle Engine project
    • Everywhere Actions
    • Exporting Assets to glTF
    • Frameworks, Bundlers, HTML
    • Testing on local devices
    • Deployment and Optimization
  • Scripting

    • Scripting in Needle Engine
    • Scripting Introduction for Unity Developers
    • Creating and using Components
    • Automatic Component Generation
    • Scripting Examples
    • Community Contributions
  • Advanced

    • VR & AR (WebXR)
    • Image Tracking (WebXR)
    • Networking
    • MaterialX
    • Editor Sync
  • Troubleshooting

    • How To Debug
    • Questions and Answers (FAQ) 💡
    • Support and Community
  • Reference

    • Feature Overview
    • Technical Overview
    • Needle Core Components
    • needle.config.json
    • <needle-engine> Configuration
    • @serializable and other decorators

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.

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.

AttributeDescription
Loading
srcPath to one or multiple glTF or glb files.
Supported types are string, string[] or a stringified array (, separated)
Loading DisplayAvailable options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing
loading-backgroundPRO — Default: transparent. Change the loading background color (e.g. #dd5500)
loading-logo-srcPRO — Change the loading logo image (e.g. https://yourdomain.com/logo.png or /logo.png)
hide-loading-overlayPRO — Do not show the loading overlay
Rendering
background-coloroptional, hex color to be used as a background color. Examples: rgb(255, 200, 100), #dddd00
background-imageoptional, URL to a skybox image (background image) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar
background-blurrinessoptional, bluriness value between 0 (no blur) and 1 (max blur) for the background-image. Example: background-blurriness="0.5"
environment-imageoptional, URL to a environment image (environment light) or a preset string: studio, blurred-skybox, quicklook, quicklook-ar
contactshadowsoptional, render contact shadows
tone-mappingoptional, supported values are none, linear, neutral, agx
tone-mapping-exposureoptional number e.g. increase exposure with tone-mapping-exposure="1.5", requires tone-mapping to be set
Interaction
autoplayadd or set to true to auto play animations e.g. <needle-engine autoplay
camera-controlsadd or set to true to automatically add OrbitControls if no camera controls are found in the scene
auto-rotateadd to enable auto-rotate (only used with camera-controls)
Events
loadstartName 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
progressName 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}) { ... }
loadfinishedName of the function to call when loading finishes
AdvancedAvailable options to change how the Needle Engine loading display looks. Use ?debugloadingrendering for easier editing
dracoDecoderPathURL to the draco decoder e.g. ./include/draco/ to use the local Draco decoder
dracoDecoderTypedraco decoder type. Options are wasm or js. See three.js documentation
ktx2DecoderPathURL to the KTX2 decoder e.g. ./include/ktx2/ to use the local KTX2 decoder
Internal
hashUsed 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

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>

Custom Loading Style (PRO)

You can easily modify how Needle Engine looks by setting the appropriate attributes on the <needle-engine> web component. Please see the table above for details.

custom loading
See code on github

Suggest changes
Last Updated: 8/22/25, 2:22 PM
Prev
needle.config.json
Next
@serializable and other decorators