Attributes of the Needle Engine Web Component

Needle Engine is typically used 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 tables below show a list of available attributes and what they do.

File Loading and Events

Custom Branding

Available attributes to change the Needle Engine loading and custom branding

Visual Settings

Interaction and Camera

Decoder Settings

For files that require a decoder (e.g. Draco compressed glb files), we automatically load an efficient decoder from the Needle CDN. If you want to create fully self-contained projects, can specify the path to the decoder with the following attributes.

Other

Loading screen (Needle Engine 6)

Needle Engine 6 renders an animated progress bar (with an optional logo) that can be themed via HTML attributes or CSS custom properties.

CSS custom properties — set any of these on the <needle-engine> element (inline style or in your CSS) to restyle the loader. A consumer value always wins over the built-in theme default:

For example, to remove the scrim entirely so the page shows through while loading:

needle-engine {
    --needle-loading-background: transparent;
    --needle-loading-blur: 0px;
}

The poster image can be styled via CSS variables, or fully via needle-engine::part(poster):

Example — a centered dark loader with a custom bar color and a darkened poster:

<needle-engine
  loading-style="dark"
  loading-layout="centered"
  poster="/poster.jpg"
  style="--needle-loading-bar:#78e08f; --needle-loading-poster-overlay:rgba(0,0,0,.5)">
</needle-engine>

Or restyle the loading bar from your stylesheet — set the variables on the <needle-engine> element (they win over the built-in theme):

needle-engine {
  --needle-loading-bar: #c9d497;                      /* fill color */
  --needle-loading-bar-track: rgba(85, 87, 12, 0.18); /* unfilled track */
  --needle-loading-bar-sheen: rgba(255, 255, 255, .5); /* animated highlight */
  --needle-loading-sheen-size: 400px;                  /* smaller = more/tighter bands */
  --needle-loading-sheen-speed: 1s;                  /* smaller = faster */
}

/* Optionally give dark mode its own bar color */
@media (prefers-color-scheme: dark) {
  needle-engine { --needle-loading-bar: #dbe6a8; }
}

Upgrade notice:

• Needle Engine 4.x–5.x: loading-style, loading-background-color, loading-text-color, primary-color, secondary-color were removed in 4.5.0, and the loading display rendered no logo since 4.10.0.
• Needle Engine 6 (alpha) reintroduces a redesigned, themeable loading screen — see Loading screen (Needle Engine 6) above. loading-style returns with a new meaning (color theme: auto/light/dark), the logo is available again (opt-in via loading-logo), and loading-logo-src becomes the loading-specific logo source (mirroring qrcode-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>