Pins HTML/SVG/Markdown to a point in the 3D scene that is ALWAYS on top — a HUD, tooltip, or badge that geometry can never hide.
JavaScript API:
OverlayAnnotationNode
This is the always-on-top member of the AbstractDomAnnotationNode annotation
family: like every annotation its content is the element's own body and it tracks a
world position as the camera moves. What distinguishes it from a
sk-live-annotation is that it never participates in depth testing — its layer
draws above all scene content and every other annotation, so it is never
occluded. That makes it the choice for UI that must stay readable no matter what is
in front of it: heads-up displays, tooltips, always-accessible panels, debug overlays.
Key attributes. The body content is the element's children (HTML, SVG, or — with
md — Markdown), not an attribute; it is real, interactive DOM with full CSS
(including animations). anchor chooses which edge sits on the world point;
scale-with-distance makes it shrink with perspective. Content is not sanitized, so
untrusted markup must be sanitized by the author first.
Related. When an annotation should read as part of the world and be hidden by
geometry in front of it, use sk-live-annotation instead; for SVG drawn into
the scene as a depth-tested texture, use sk-rasterized-annotation.
Serve these docs to run the live example.
WebGPU needs a secure context — open this page via grunt serve
rather than double-clicking the file. The Markup tab works from disk.
<!-- An overlay annotation tracks a world position like any annotation, but its
layer always draws on top — nothing in the scene can hide it. Here a label
is pinned above the sphere; a second cube passes IN FRONT of the sphere
without ever covering the label, which is the always-on-top behaviour a HUD
or tooltip needs. Content is the element BODY. -->
<sk-scene>
<sk-plain-material id="mat" base-color="#7fa8d8"></sk-plain-material>
<sk-plain-material id="fg" base-color="#e0b050"></sk-plain-material>
<sk-sphere radius="1" segments="6"><sk-surface-paint material="#mat"></sk-surface-paint></sk-sphere>
<!-- A cube sweeping in front, at the label's own height — it crosses the
label's screen region but NEVER hides the always-on-top overlay. -->
<sk-cube y="1.5" z="2" size="0.9">
<sk-surface-paint material="#fg"></sk-surface-paint>
<sk-animation duration="3000ms" iterations="Infinity" direction="alternate">
<sk-keyframe offset="0" x="-2.5"></sk-keyframe>
<sk-keyframe offset="1" x="2.5"></sk-keyframe>
</sk-animation>
</sk-cube>
<!-- Always-on-top label at the same height the cube sweeps through. -->
<sk-overlay-annotation y="1.5" anchor="center">
<div style="background: rgba(0,0,0,0.8); color: white; padding: 8px 12px;
font: 13px sans-serif;">always on top</div>
</sk-overlay-annotation>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
id |
<id> |
— | The element's unique identifier — the standard HTML global id attribute. |
draggable |
<boolean> |
false |
Gets whether this node can be dragged. |
xanimatable |
<number> |
0 |
X position. |
yanimatable |
<number> |
0 |
Y position. |
zanimatable |
<number> |
0 |
Z position. |
hanimatable |
<angle> |
0 |
Heading (Y-axis rotation) in radians. |
panimatable |
<angle> |
0 |
Pitch (X-axis rotation) in radians. |
banimatable |
<angle> |
0 |
Bank (Z-axis rotation) in radians. |
quaternionanimatable |
<quaternion> ({ <number>, <number>, <number>, <number> }) |
— | Rotation as quaternion (overrides h, p, b if provided) |
sxanimatable |
<number> |
1 |
X-axis scale factor. |
syanimatable |
<number> |
1 |
Y-axis scale factor. |
szanimatable |
<number> |
1 |
Z-axis scale factor. |
s |
<number> |
— | Uniform scale factor for all axes (overrides sx, sy, sz if provided) write-only |
md |
<boolean> |
false |
When true, treat AbstractDomAnnotationConfig.content as |
anchor |
<anchor> ("center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right") |
"center" |
The anchor point for positioning the annotation. |
scale-with-distance |
<boolean> |
false |
If true, maintains constant screen size; if false, scales with perspective. |
Standard DOM event-handler content attributes — the value is JavaScript run when the event fires. They behave exactly as on any HTML element.
onclick, ondblclick, onauxclick, oncontextmenu, onpointerdown, onpointerup, onpointermove, onpointercancel, onpointerover, onpointerout, onpointerenter, onpointerleave, ongotpointercapture, onlostpointercapture, onwheel, ondragstart, ondrag, ondragenter, ondragover, ondragleave, ondrop, ondragend