The <splat-viewer> element

<script type="module" src="/splat-viewer-0.1.0/splat-viewer.0.1.0.js"></script>

<splat-viewer src="/products/chair.sog" view="/products/chair.view.json" alt="Oak chair">
  <img src="/products/chair.webp" alt="Oak chair" width="2048" height="2048">
</splat-viewer>

The <img> inside is the poster: it shows at once, and the 3D view replaces it when ready. If anything fails, the poster stays.

Attributes

Attributes are read once, when the viewer starts.

Events

The usage events (load, first-interaction, view-time) are for your own analytics. They go only to your page, carry no personal data (only times, a count and error codes) and nothing is sent to any server. first-interaction and view-time bubble, so one listener on document hears every viewer. The one exception: the view-time sent when an element is removed is no longer in the page, so only a listener on the element itself hears it. For example:

document.addEventListener('first-interaction', (e) => analytics.track('3d_interaction', { ms: e.detail.ms }));

Preset views

Add your own buttons inside the element; a click turns the camera to that view:

<splat-viewer src="/products/chair.sog" auto-rotate>
  <img src="/products/chair.webp" alt="Oak chair">
  <button slot="view" data-camera-orbit="0deg 75deg 100%">Front</button>
  <button slot="view" data-camera-orbit="90deg 75deg 100%">Side</button>
  <button slot="view" data-camera-orbit="0deg 20deg 80%">Top</button>
</splat-viewer>

data-camera-orbit is the angle around the product from the front, the angle down from straight above, and the distance as a share of the start view’s (optional). The view file’s limits still apply. The buttons are yours: style and word them as you like.

Hotspots

Pin your own labels to points on the product:

<splat-viewer src="/products/drill.sog">
  <img src="/products/drill.webp" alt="Hammer drill">
  <button slot="hotspot" data-position="0.02 0.11 0.05" data-normal="0 0 1">Chuck</button>
</splat-viewer>

• data-position: the point, in the product file’s own coordinates (x y z).
• data-normal: the direction the surface faces there (x y z). The label hides while that side faces away from the shopper. Without it, the label hides only when its point is behind the camera.
• The labels are yours: buttons, links or text, styled and worded as you like. Visible ones are in the keyboard’s tab order and read by screen readers; hidden ones are not.

React, Vue and other frameworks

The element works as it is, with no wrapper:

• Set attributes as usual. Changing src loads the new product in the same element.
• Vue: tell Vue the tag is not one of its components, app.config.compilerOptions.isCustomElement = (tag) => tag === 'splat-viewer', then listen with @load, @error, @first-interaction, @view-time.
• React: listen through a ref, ref.current.addEventListener('load', …), which works in React 18 and 19.

Shoppers

• Mouse: drag turns, right-drag or Shift-drag moves, double-click resets. The wheel zooms only after the viewer is clicked; before that it scrolls the page.
• Touch: one finger turns left and right, up-down swipes scroll the page, two fingers zoom and move, a double tap resets.
• Keyboard, once the viewer has focus: arrows turn, + and - zoom, Home or 0 resets.

Styling

Size the element with your own CSS, such as width: 100%; aspect-ratio: 1. It is 300 × 300 pixels if you set nothing, and stays square if you set only a width. For a wider box use aspect-ratio: 4/3 or aspect-ratio: 16/9: the 3D view keeps the same framing from top to bottom and shows more at the sides. Make the poster in the same shape (the view editor’s Shape and Download poster), or it shows smaller until the 3D view replaces it.

Custom properties, set on the element or any parent:

Parts, for any other CSS through ::part():

Your own loading text and hint, for example in another language:

<splat-viewer src="/products/chair.sog">
  <img src="/products/chair.webp" alt="Stolica od hrasta">
  <span slot="loading">Učitavanje 3D prikaza…</span>
  <span slot="prompt">Prevucite da okrenete</span>
</splat-viewer>

Example:

splat-viewer {
  --splat-viewer-accent-color: #e4572e;
  --splat-viewer-panel-color: #1d3557;
}
splat-viewer::part(loading) { text-transform: uppercase; }