Guided pointer

Effects

An illustrated pointer moves between story waypoints, with a small arrival or hold cue.

React · copy into your project · light and dark themes

Try it

Variant

Notice an ideaMake a little room.

Choose a directionOne useful next step.

Stay with itA moment to consider.

Notice an idea · moment 1 of 3

An illustrated pointer; the story cards are a preview.

Loading preview…

Take it with you

Copy the example, API and usage notes for your editor or AI assistant.

Add to your project

Terminal

npx shadcn@latest add https://luv-jeri.github.io/cojeev-ui/r/guided-pointer.json

The command includes the component’s shared dependencies. Your project keeps editable source files.

Include the complete example

This example also composes button. Install its parts together:

Terminal

npx shadcn@latest add https://luv-jeri.github.io/cojeev-ui/r/button.json https://luv-jeri.github.io/cojeev-ui/r/guided-pointer.json

Using guided pointer

Place GuidedPointer inside a positioned container. Supply points with unique id and normalized x/y coordinates; activeId selects the current waypoint.
Use real buttons outside the illustration to move through the story. The overlay does not click, replace the system cursor or intercept input.
Choose arrow or hand, set duration in milliseconds (up to two seconds), and change replayKey for another arrival cue. Point click adds a finite ring; pressed adds a held pose.
Coordinates are clamped to the available area after accounting for size. An omitted activeId selects the first valid point; a missing ID or empty points hides the pointer.

API

Compose the exported parts below. The prop types are read from the React source during the registry build.

Native element or underlying primitive props are inherited where declared, including accessible labels, event handlers and refs.

GuidedPointerProps

Prop	Type	Required
`points`	`readonly GuidedPointerPoint[]`	Yes
`activeId` Omit to use the first valid point. An unknown ID hides the pointer.	`string`	No
`duration` Milliseconds per move, capped at two seconds.	`number`	No
`replayKey` Change to repeat a finite arrival cue at the current waypoint.	`string \| number`	No
`glyph`	`"arrow" \| "hand"`	No
`size` Glyph size in pixels. Coordinates use the stage area minus this size.	`number`	No

Accessibility

The overlay is inert, hidden from assistive technology and cannot receive focus.
Provide accessible descriptions and controls for the story itself. Quiet and offscreen states settle to the destination without a pulse.

States and appearance

stillmovingpressedarrivalemptyreduced-motion

For conditional content, keep a MotionPresence boundary around keyed MotionSurface children. The shared entrance and exit states work with native primitives and respect your motion preference.

Try pointer and keyboard interaction, and switch the appearance control in the navigation to compare light and dark mode. Motion respects reduced motion preferences.