KQ-1844 · GUEST/POINTERS
Guest Pointers
A shared document visited by named collaborator pointers replaying recorded paths against its measured anchors: they glide, hover, drag-select words in their own colour, leave short chat bubbles and tick boxes or press buttons, each on a loop of its own. Positions arrive the way a network delivers them, as samples a few times a second, and the smoothing prop is a critically damped follower between them, from jumpy to buttery, with each name tag trailing its tip on springs.snap. Clicking a tag or a name in the presence toolbar follows that guest — the view zooms in and pans with them on a glide-stiff, critically damped camera and the frame takes their colour — and Escape (or the chip's button) goes back to the overview.
Coldbrook · launch plan
Live with the team
A shared document with 3 people in it. Use the People here toolbar to follow someone; the view moves with them. Escape stops following.
3 here · overview
Install
One command — the source lands in your repo. Or copy it from the Code tab.
$ pnpm dlx shadcn@latest add @kinetiq/guest-pointers
Props
- guests
- GuestPointer[]
- default defaultGuests
- Who might be here: { id, name, color?, steps? }, steps being the recorded path against the document's anchors.
- count
- number
- default 3
- How many of them are here, 1 to 5.
- tagStyle
- "pill" | "flag" | "initials"
- default "pill"
- How a pointer's name is worn: a pill beside it, a flag at its tip, or initials.
- smoothing
- number
- default 0.6
- How the pointers glide between the samples the network delivers, 0 (jumps) to 1 (buttery, a little behind).
- following / defaultFollowing
- string | null
- default null
- The guest the view follows, or null for the overview; controlled or initial.
- onFollowingChange
- (id: string | null) => void
- default —
- Fires from the tag, button or Escape that started or stopped following.
- speed
- number
- default 1
- Replay speed, 0.5 to 2.
- sampleRate
- number
- default 12
- Samples a second the network delivers per pointer.
- bubbles
- boolean
- default true
- Guests leave chat bubbles.
- selections
- boolean
- default true
- Guests select text.
- followZoom
- number
- default 1
- Zoom while following; never less than the overview.
- title
- string
- default "Spring launch plan"
- The document's title.
- paused
- boolean
- default false
- Stop the replay where it is.
- label
- string
- default "Shared document"
- The view's accessible name.
- className
- string
- default "h-[520px] w-full"
- Sizes the view.
| Prop | Type | Default | Description |
|---|---|---|---|
| guests | GuestPointer[] | defaultGuests | Who might be here: { id, name, color?, steps? }, steps being the recorded path against the document's anchors. |
| count | number | 3 | How many of them are here, 1 to 5. |
| tagStyle | "pill" | "flag" | "initials" | "pill" | How a pointer's name is worn: a pill beside it, a flag at its tip, or initials. |
| smoothing | number | 0.6 | How the pointers glide between the samples the network delivers, 0 (jumps) to 1 (buttery, a little behind). |
| following / defaultFollowing | string | null | null | The guest the view follows, or null for the overview; controlled or initial. |
| onFollowingChange | (id: string | null) => void | — | Fires from the tag, button or Escape that started or stopped following. |
| speed | number | 1 | Replay speed, 0.5 to 2. |
| sampleRate | number | 12 | Samples a second the network delivers per pointer. |
| bubbles | boolean | true | Guests leave chat bubbles. |
| selections | boolean | true | Guests select text. |
| followZoom | number | 1 | Zoom while following; never less than the overview. |
| title | string | "Spring launch plan" | The document's title. |
| paused | boolean | false | Stop the replay where it is. |
| label | string | "Shared document" | The view's accessible name. |
| className | string | "h-[520px] w-full" | Sizes the view. |