Skip to content
/ghost-cursor

API

Three components and one JSON format. <GhostCursor> plays a recording, and records too when you open the page with ?record in development. <DevRecorder> shows the record toolbar in development only. <Recorder> records in every environment.

GhostCursor

Use it for every demo you publish. You never need a second component to make a take. GhostReplay is the same component under another name; the agent skill’s snippets use it.

PropTypeDefaultDescription
recording requiredRecordingThe take to replay. Import it from the JSON file the recorder produced.
children requiredReactNodeThe component. It renders as usual and stays usable for the reader.
classNamestringClasses for the box the ghost moves in. The box is at least 240px tall. Set its height here.
styleCSSPropertiesInline styles for the box.
loopDelaynumber1600How long the final state stays on screen before the take starts over, in ms.

DevRecorder

The record toolbar around children in next dev, and children alone in a production build, so you don’t need a NODE_ENV check. It takes the same props as <Recorder>.

import { DevRecorder } from "@imuratalpay/ghost-cursor";

<DevRecorder style={{ height: 320 }}>
  <LikeButton />
</DevRecorder>

Recorder

Use it when recording has to work outside development, for example on an authoring page or in a demo of the recorder itself. For published demos, use <GhostCursor>.

PropTypeDefaultDescription
children requiredReactNodeThe component to record.
classNamestringClasses for the box.
styleCSSPropertiesInline styles for the box.
onRecord(recording) => voidCalled when Stop ends a take that has at least one event.
captureSyntheticbooleanfalseAlso record events that scripts dispatch. Turn it on only when a GhostCursor replays a demo of the recorder.

Attributes

You set data-ghost-id. The ghost sets the other three on the elements it touches and removes them when it moves on, because a script can’t switch on the real CSS states.

AttributeSet byMeaning
data-ghost-idYouA name for the recorder to use instead of a CSS path. Put one on every element a take clicks or types into.
data-ghost-hoverGhostMirrors :hover on the element under the ghost and its ancestors.
data-ghost-activeGhostMirrors :active while the ghost holds a press.
data-ghost-focusGhostMarks the element a real press would have focused. Real focus never moves during a replay.

With Tailwind CSS v4, override the variants in your stylesheet and your components need no changes.

app/globals.css
@custom-variant hover {
  @media (hover: hover) and (pointer: fine) {
    &:hover { @slot; }
  }
  &[data-ghost-hover] { @slot; }
}

@custom-variant active {
  &:active { @slot; }
  &[data-ghost-active] { @slot; }
}

@custom-variant focus {
  &:focus { @slot; }
  &[data-ghost-focus] { @slot; }
}

Colors

Every color in the stylesheet is a variable on .gc-root, and the defaults are a light theme. Map them to your own tokens to follow your color scheme.

.gc-root {
  --gc-fg: var(--fg-1);        /* buttons and icons */
  --gc-muted: var(--fg-3);     /* time, hints */
  --gc-stage: var(--stage);    /* the box */
  --gc-surface: var(--surface);
  --gc-line: var(--line);
}

Behavior

WhenThe player
The reader’s mouse enters the boxFades the ghost out and stops the playhead. The component is the reader’s.
The reader leaves without clicking or typingFades the ghost back in after 420ms and continues from where it stopped.
The reader leaves after clicking or typingRemounts the component to its first frame and starts the take over.
The reader tabs into the boxSteps aside the same way, until focus leaves the box.
The box scrolls out of view, or the tab is hiddenPauses.
The reader prefers reduced motionDoesn’t autoplay. It shows the first frame and a Play button that runs the take once.
The take endsHolds the final state for loopDelay. If the DOM changed, it cross-fades back to the first frame.

Clicks wait for the cursor. The drawn arrow trails the recorded path because it runs through a spring, so the playhead holds each press until the tip is within 3px of its target.

Keyboard

KeyWhereAction
SpacePointer over the demo, or focus in its controlsPause or resume
← →ScrubberSeek 250ms, or 1s with Shift
Home EndScrubberJump to the start or the end

Inside the box, every key goes to the component.

Recording format

One JSON object per take. Coordinates run from 0 to 1 across the box. Each press also stores where it landed inside its target, so a take recorded at one width still hits its targets at another.

type Recording = {
  v: 1;
  size: [width: number, height: number]; // box size while recording, in px
  targets: string[];                     // "@name", or a CSS path from the content root
  events: (
    | [t: number, "m", x: number, y: number]                         // move
    | [t: number, "d" | "u" | "c", x: number, y: number,
       target?: number, offsetX?: number, offsetY?: number]          // down, up, click
    | [t: number, "k", key: string, target?: number, mods?: number]  // key press
  )[];
};

Limits

The ghost dispatches events. It isn’t a browser. A component that calls setPointerCapture during a replay throws, because the synthetic pointer isn’t active. Recorded Tab presses don’t move focus. Enter and Space activate buttons and checkboxes the way a browser would, and typing works in text inputs and textareas.