Pins a node to a fixed spot on the screen, ignoring camera motion — the way to make HUD markers, screen-space labels, and UI overlays inside a 3D scene.
JavaScript API:
ViewportPositionConstraint
This is the screen-space member of the Constraint family, and the odd one
out: instead of reading another scene object, it reads the viewport. Like every
constraint it drives its constrained
target by recomputing each frame — here it converts a screen position into world
space against the current camera, so the target stays glued to that screen spot
however the camera pans, orbits, or zooms.
Key attributes. mode chooses how the screen position is expressed: px
(absolute CSS pixels, the default), percent (0–100 of viewport width/height, so
it survives resizing), or anchor (offsets from a named corner/edge). In anchor
mode, anchor names the reference point (e.g. top-left, bottom-right). x
and y give the position or offset in the chosen mode's units, and z is the
normalized-device depth (0 = near plane, 1 = far plane) that controls what the
pinned node draws in front of or behind.
Related. It commonly pins annotation nodes (sk-live-annotation,
sk-overlay-annotation). Unlike the other members of the
Constraint family — sk-align-to-spline-constraint,
sk-orbit-constraint, sk-target-at-constraint — it constrains to
the screen rather than to another node; the GPU-parallel PointConstraint
applies per-clone effects across a Cloner.
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.
<!-- Pins the host to a screen-space anchor (HUD-like), ignoring camera motion.
`mode="anchor"` + `anchor="top-left"` picks the corner; `x`/`y` offset the
node inward from it (here 60px right, 60px down). -->
<sk-scene>
<sk-plain-material id="mat" base-color="#7fa8d8"></sk-plain-material>
<!-- Pinned 60px in from the top-left corner of the viewport -->
<sk-sphere radius="0.5" segments="6">
<sk-surface-paint material="#mat"></sk-surface-paint>
<sk-viewport-position-constraint mode="anchor" anchor="top-left" x="60" y="60"></sk-viewport-position-constraint>
</sk-sphere>
</sk-scene>| Attribute | Type | Default | Description |
|---|---|---|---|
modeanimatable |
<viewport-position-mode> ("px" | "percent" | "anchor") |
— | Positioning mode. |
anchor |
<anchor> ("center" | "top" | "bottom" | "left" | "right" | "top-left" | "top-right" | "bottom-left" | "bottom-right") |
— | Viewport anchor point (required when mode is 'anchor'). |
x |
<number> |
— | X coordinate: CSS pixels (px mode), percentage 0–100 (percent mode), |
y |
<number> |
— | Y coordinate: CSS pixels (px mode), percentage 0–100 (percent mode), |
z |
<number> |
— | The Z depth in normalized device coordinates (NDC). |