3D
model-annotations
Labels pinned to points on a 3D model that follow them as the model turns, each a button that opens its note, hidden while its point is behind the camera or out of view; the same notes are always given as a list, so nobody has to find them by turning.
When to use it
Pointing out parts of a 3D object: the parts of a machine, features of a building, finds on a scan. Put the tracker inside the scene and the labels over it, in the same positioned box. For a flat picture use hotspots; for a model with no notes use model-viewer.
See it working
The demonstration the browser checks drive, with the keyboard as well as the pointer. More of it is on the Effects and 3D data page.
Word rotate and pattern
Maps for teams, schools, or newsrooms
Animated beam
A map becomes a film.
Orbit
- Maps
- Charts
- Films
- Motion
Confetti
Not yet published.
Point cloud
- Clay
- Stone
- Glass
| # | width | height | kind |
|---|---|---|---|
| 1 | 0.2 | 1.2 | Clay |
| 2 | 0.2 | 2.1 | Clay |
| 3 | 0.2 | 2.5 | Clay |
| 4 | 0.3 | 0.6 | Clay |
| 5 | 0.3 | 2.2 | Clay |
| 6 | 0.3 | 2.5 | Clay |
| 7 | 0.4 | 0.5 | Clay |
| 8 | 0.5 | 0.6 | Clay |
| 9 | 0.5 | 2.1 | Clay |
| 10 | 0.6 | 1.4 | Clay |
| 11 | 0.7 | 0.7 | Clay |
| 12 | 0.8 | 1.4 | Clay |
| 13 | 0.9 | 0.6 | Clay |
| 14 | 1 | 0.5 | Clay |
| 15 | 1.1 | 2.2 | Clay |
| 16 | 1.2 | 0.6 | Clay |
| 17 | 1.2 | 1.1 | Stone |
| 18 | 1.2 | 1.2 | Stone |
| 19 | 1.2 | 1.2 | Stone |
| 20 | 1.2 | 2.5 | Clay |
| 21 | 1.3 | 1.1 | Clay |
| 22 | 1.3 | 1.3 | Stone |
| 23 | 1.3 | 1.7 | Stone |
| 24 | 1.3 | 2 | Stone |
| 25 | 1.5 | 2.5 | Clay |
| 26 | 1.5 | 2.6 | Stone |
| 27 | 1.5 | 2.8 | Stone |
| 28 | 1.6 | 1.3 | Clay |
| 29 | 1.6 | 2.1 | Clay |
| 30 | 1.6 | 3.1 | Stone |
| 31 | 1.7 | 2 | Clay |
| 32 | 1.7 | 3.1 | Stone |
| 33 | 1.8 | 2 | Clay |
| 34 | 1.8 | 2.9 | Stone |
| 35 | 1.8 | 3.1 | Stone |
| 36 | 1.9 | 1.2 | Clay |
| 37 | 1.9 | 2.7 | Stone |
| 38 | 2 | 2.5 | Clay |
| 39 | 2.1 | 0.6 | Clay |
| 40 | 2.1 | 2.2 | Clay |
| 41 | 2.1 | 2.7 | Stone |
| 42 | 2.2 | 0.7 | Clay |
| 43 | 2.2 | 1.3 | Clay |
| 44 | 2.2 | 1.5 | Clay |
| 45 | 2.2 | 2 | Stone |
| 46 | 2.2 | 2.6 | Glass |
| 47 | 2.2 | 2.6 | Stone |
| 48 | 2.2 | 3.4 | Glass |
| 49 | 2.2 | 3.7 | Glass |
| 50 | 2.3 | 1.8 | Stone |
| 51 | 2.3 | 3.7 | Glass |
| 52 | 2.4 | 1.7 | Glass |
| 53 | 2.4 | 1.8 | Glass |
| 54 | 2.4 | 3.3 | Glass |
| 55 | 2.5 | 1.3 | Stone |
| 56 | 2.6 | 1.2 | Stone |
| 57 | 2.6 | 1.8 | Glass |
| 58 | 2.6 | 2.4 | Glass |
| 59 | 2.7 | 1.2 | Stone |
| 60 | 2.7 | 2.3 | Glass |
| 61 | 2.8 | 1.2 | Stone |
| 62 | 2.9 | 1.3 | Stone |
| 63 | 2.9 | 1.7 | Stone |
| 64 | 2.9 | 2.5 | Glass |
| 65 | 3 | 1.7 | Glass |
| 66 | 3 | 1.9 | Stone |
| 67 | 3 | 3.2 | Glass |
| 68 | 3.1 | 1.8 | Glass |
| 69 | 3.1 | 1.8 | Stone |
| 70 | 3.1 | 2.1 | Stone |
| 71 | 3.1 | 2.6 | Stone |
| 72 | 3.1 | 2.8 | Stone |
| 73 | 3.2 | 2.7 | Stone |
| 74 | 3.2 | 3.1 | Stone |
| 75 | 3.3 | 1.9 | Glass |
| 76 | 3.4 | 2.5 | Glass |
| 77 | 3.4 | 3.7 | Glass |
| 78 | 3.5 | 3.5 | Glass |
| 79 | 3.7 | 2.7 | Glass |
| 80 | 3.7 | 3.4 | Glass |
| 81 | 3.8 | 2.6 | Glass |
| 82 | 3.8 | 3.4 | Glass |
| 83 | 4 | 1.9 | Glass |
| 84 | 4 | 2.5 | Glass |
| 85 | 4 | 3.7 | Glass |
| 86 | 4.1 | 3.3 | Glass |
| 87 | 4.2 | 1.8 | Glass |
| 88 | 4.2 | 2.3 | Glass |
| 89 | 4.2 | 2.4 | Glass |
| 90 | 4.2 | 3.2 | Glass |
| # | width | height | depth | kind |
|---|---|---|---|---|
| 1 | 1.2 | 2.5 | 2.5 | Clay |
| 2 | 3.2 | 2.7 | 3.2 | Stone |
| 3 | 2.9 | 2.5 | 3.8 | Glass |
| 4 | 0.3 | 0.6 | 4.3 | Clay |
| 5 | 2.7 | 1.2 | 4.5 | Stone |
| 6 | 4 | 2.5 | 4.4 | Glass |
| 7 | 0.5 | 2.1 | 4.1 | Clay |
| 8 | 1.6 | 3.1 | 3.5 | Stone |
| 9 | 4.1 | 3.3 | 2.9 | Glass |
| 10 | 1.6 | 1.3 | 2.1 | Clay |
| 11 | 1.2 | 1.2 | 1.4 | Stone |
| 12 | 3.1 | 1.8 | 0.9 | Glass |
| 13 | 2.2 | 1.3 | 0.6 | Clay |
| 14 | 2.1 | 2.7 | 0.5 | Stone |
| 15 | 2.2 | 3.7 | 0.7 | Glass |
| 16 | 1.6 | 2.1 | 1.2 | Clay |
| 17 | 3.1 | 1.8 | 1.8 | Stone |
| 18 | 2.6 | 1.8 | 2.5 | Glass |
| 19 | 0.5 | 0.6 | 3.2 | Clay |
| 20 | 3 | 1.9 | 3.9 | Stone |
| 21 | 3.7 | 3.4 | 4.3 | Glass |
| 22 | 0.3 | 2.5 | 4.5 | Clay |
| 23 | 1.9 | 2.7 | 4.4 | Stone |
| 24 | 4.2 | 2.4 | 4.1 | Glass |
| 25 | 1.2 | 0.6 | 3.5 | Clay |
| 26 | 1.2 | 1.2 | 2.8 | Stone |
| 27 | 3.4 | 2.5 | 2.1 | Glass |
| 28 | 2.1 | 2.2 | 1.4 | Clay |
| 29 | 1.7 | 3.1 | 0.9 | Stone |
| 30 | 2.4 | 3.3 | 0.6 | Glass |
| 31 | 1.9 | 1.2 | 0.5 | Clay |
| 32 | 2.8 | 1.2 | 0.7 | Stone |
| 33 | 2.4 | 1.8 | 1.2 | Glass |
| 34 | 0.8 | 1.4 | 1.8 | Clay |
| 35 | 3.1 | 2.8 | 2.5 | Stone |
| 36 | 3.4 | 3.7 | 3.2 | Glass |
| 37 | 0.2 | 2.1 | 3.9 | Clay |
| 38 | 2.3 | 1.8 | 4.3 | Stone |
| 39 | 4.2 | 1.8 | 4.5 | Glass |
| 40 | 0.9 | 0.6 | 4.4 | Clay |
| 41 | 1.3 | 2 | 4.1 | Stone |
| 42 | 3.8 | 3.4 | 3.5 | Glass |
| 43 | 2 | 2.5 | 2.8 | Clay |
| 44 | 1.5 | 2.6 | 2.1 | Stone |
| 45 | 2.6 | 2.4 | 1.4 | Glass |
| 46 | 2.1 | 0.6 | 0.9 | Clay |
| 47 | 2.5 | 1.3 | 0.6 | Stone |
| 48 | 2.2 | 2.6 | 0.5 | Glass |
| 49 | 1.1 | 2.2 | 0.7 | Clay |
| 50 | 3.2 | 3.1 | 1.2 | Stone |
| 51 | 3 | 3.2 | 1.8 | Glass |
| 52 | 0.2 | 1.2 | 2.5 | Clay |
| 53 | 2.6 | 1.2 | 3.3 | Stone |
| 54 | 4 | 1.9 | 3.9 | Glass |
| 55 | 0.6 | 1.4 | 4.3 | Clay |
| 56 | 1.5 | 2.8 | 4.5 | Stone |
| 57 | 4 | 3.7 | 4.4 | Glass |
| 58 | 1.7 | 2 | 4.1 | Clay |
| 59 | 1.3 | 1.7 | 3.5 | Stone |
| 60 | 3 | 1.7 | 2.8 | Glass |
| 61 | 2.2 | 0.7 | 2.1 | Clay |
| 62 | 2.2 | 2 | 1.4 | Stone |
| 63 | 2.2 | 3.4 | 0.9 | Glass |
| 64 | 1.5 | 2.5 | 0.6 | Clay |
| 65 | 3.1 | 2.6 | 0.5 | Stone |
| 66 | 2.7 | 2.3 | 0.7 | Glass |
| 67 | 0.4 | 0.5 | 1.2 | Clay |
| 68 | 2.9 | 1.3 | 1.8 | Stone |
| 69 | 3.8 | 2.6 | 2.6 | Glass |
| 70 | 0.3 | 2.2 | 3.3 | Clay |
| 71 | 1.8 | 3.1 | 3.9 | Stone |
| 72 | 4.2 | 3.2 | 4.3 | Glass |
| 73 | 1.3 | 1.1 | 4.5 | Clay |
| 74 | 1.2 | 1.1 | 4.4 | Stone |
| 75 | 3.3 | 1.9 | 4.1 | Glass |
| 76 | 2.2 | 1.5 | 3.5 | Clay |
| 77 | 1.8 | 2.9 | 2.8 | Stone |
| 78 | 2.3 | 3.7 | 2.1 | Glass |
| 79 | 1.8 | 2 | 1.4 | Clay |
| 80 | 2.9 | 1.7 | 0.9 | Stone |
| 81 | 2.4 | 1.7 | 0.6 | Glass |
| 82 | 0.7 | 0.7 | 0.5 | Clay |
| 83 | 3.1 | 2.1 | 0.7 | Stone |
| 84 | 3.5 | 3.5 | 1.2 | Glass |
| 85 | 0.2 | 2.5 | 1.8 | Clay |
| 86 | 2.2 | 2.6 | 2.6 | Stone |
| 87 | 4.2 | 2.3 | 3.3 | Glass |
| 88 | 1 | 0.5 | 3.9 | Clay |
| 89 | 1.3 | 1.3 | 4.3 | Stone |
| 90 | 3.7 | 2.7 | 4.5 | Glass |
Model annotations
- Lid — Hinged at the back.
- Side — A handle was here.
- Front — The maker's mark.
Add it
npx shadcn@latest add @rivier-ui/model-annotations
The registry is named once in components.json: see Installation.
Example
Import it from @/components/three/model-annotations.
const store = useAnnotationStore();
<div className="relative">
<Scene label="A vase" aspect={1}>
<ModelStage><Vase /></ModelStage>
<ModelAnnotationTracker store={store} points={[{ id: "handle", position: [0.6, 0.4, 0] }]} />
</Scene>
<ModelAnnotations store={store} annotations={[{ id: "handle", label: "Handle", note: "Added later, in a darker clay." }]} />
</div>
What it needs
A client component: it uses state, effects or browser behaviour. Packages: @react-three/fiber, three.
It imports
Source
The whole file. Once copied it is yours: the registry item holds the same text.
"use client";
/**
* @name model-annotations
* @category three
* @description Labels pinned to points on a 3D model that follow them as the model turns, each a button that opens its note, hidden while its point is behind the camera or out of view; the same notes are always given as a list, so nobody has to find them by turning.
* @when Pointing out parts of a 3D object: the parts of a machine, features of a building, finds on a scan. Put the tracker inside the scene and the labels over it, in the same positioned box. For a flat picture use hotspots; for a model with no notes use model-viewer.
* @example
* const store = useAnnotationStore();
* <div className="relative">
* <Scene label="A vase" aspect={1}>
* <ModelStage><Vase /></ModelStage>
* <ModelAnnotationTracker store={store} points={[{ id: "handle", position: [0.6, 0.4, 0] }]} />
* </Scene>
* <ModelAnnotations store={store} annotations={[{ id: "handle", label: "Handle", note: "Added later, in a darker clay." }]} />
* </div>
*/
import { useFrame, useThree } from "@react-three/fiber";
import { useRef, useState, type ComponentProps } from "react";
import { Vector3 } from "three";
import { cn } from "@/lib/cn";
/** Connects the tracker in the canvas to the labels on the page: the tracker writes each label's place straight onto it every frame. */
export type AnnotationStore = { elements: Map<string, HTMLElement> };
/** A store for one set of annotations. */
export function useAnnotationStore(): AnnotationStore {
const [store] = useState<AnnotationStore>(() => ({ elements: new Map() }));
return store;
}
export type AnnotationPoint = { id: string; position: readonly [number, number, number] };
/** Inside the scene: projects each point to the canvas every frame and moves its label there. */
export function ModelAnnotationTracker({ store, points }: { store: AnnotationStore; points: readonly AnnotationPoint[] }) {
const camera = useThree((state) => state.camera);
const size = useThree((state) => state.size);
const scratch = useRef(new Vector3());
useFrame(() => {
for (const point of points) {
const element = store.elements.get(point.id);
if (!element) continue;
const v = scratch.current.set(point.position[0], point.position[1], point.position[2]);
// The point in the camera's space: behind the camera when z is past 1 after projection.
v.project(camera);
const visible = v.z < 1 && Math.abs(v.x) <= 1.05 && Math.abs(v.y) <= 1.05;
element.style.transform = `translate(${((v.x + 1) / 2) * size.width}px, ${((1 - v.y) / 2) * size.height}px) translate(-50%, -50%)`;
element.dataset["hidden"] = visible ? "false" : "true";
}
});
return null;
}
export type ModelAnnotation = { id: string; label: string; note?: string };
export type ModelAnnotationsProps = Omit<ComponentProps<"div">, "children"> & {
store: AnnotationStore;
annotations: readonly ModelAnnotation[];
/** The heading of the list of notes. Default "Notes". */
listLabel?: string;
};
/** Over the scene: a button per point, and under it the same notes as a list. */
export function ModelAnnotations({ store, annotations, listLabel = "Notes", className, ...props }: ModelAnnotationsProps) {
const [open, setOpen] = useState<string | null>(null);
return (
<>
<div data-slot="model-annotations" aria-hidden="true" className={cn("pointer-events-none absolute inset-0 overflow-hidden", className)} {...props}>
{annotations.map((annotation, index) => (
<div
key={annotation.id}
ref={(node) => {
if (node) store.elements.set(annotation.id, node);
else store.elements.delete(annotation.id);
}}
data-hidden="true"
// Placed from the canvas's own left edge: the projection is in screen pixels, which do not mirror.
className="pointer-events-auto absolute left-0 top-0 transition-opacity duration-instant data-[hidden=true]:pointer-events-none data-[hidden=true]:opacity-0 motion-reduce:transition-none"
>
<button
type="button"
tabIndex={-1}
onClick={() => setOpen(open === annotation.id ? null : annotation.id)}
className="flex items-center gap-1.5 rounded-control border bg-background px-2 py-1 text-xs font-medium"
>
<span className="flex size-5 items-center justify-center rounded-full bg-primary text-primary-foreground tabular-nums">{index + 1}</span>
{annotation.label}
</button>
{open === annotation.id && annotation.note ? <p className="mt-1 max-w-56 rounded-surface border bg-popover p-2 text-xs text-popover-foreground">{annotation.note}</p> : null}
</div>
))}
</div>
<ol data-slot="model-annotations-list" aria-label={listLabel} className="mt-3 flex flex-col gap-1 text-sm">
{annotations.map((annotation, index) => (
<li key={annotation.id} className="flex gap-2">
<span aria-hidden="true" className="flex size-5 shrink-0 items-center justify-center rounded-full bg-primary text-xs text-primary-foreground tabular-nums">
{index + 1}
</span>
<span>
<span className="font-medium">{annotation.label}</span>
{annotation.note ? <span className="text-muted-foreground"> — {annotation.note}</span> : null}
</span>
</li>
))}
</ol>
</>
);
}