# Live cursors

A React component in [Beamline](https://beamline.io/)'s [Content & display](https://beamline.io/components/display) category. Live demo: https://beamline.io/components/live-cursors

Who else is working on this, and where: over any shared surface, each person's pointer in the colour their name always gets, with a name flag, gliding between the positions your realtime service sends; their selections outlined in the same colour, a short message beside the pointer when they type one (press / for your own), quieter when they go idle and fading when they leave. Positions are fractions of the surface, so every screen size agrees.

## Use it for

- A canvas, board, document or dashboard several people edit at once: show where each one is pointing and what they have selected.
- Cursor chat: a quick word at the place it is about, without opening comments.

## Not for

- The faces of who is here ([avatar-group](https://beamline.io/components/avatar-group), with a presence status on each Avatar).
- Comments that stay ([comment-thread](https://beamline.io/components/comment-thread)).
- A conversation ([chat-thread](https://beamline.io/components/chat-thread)).

## Anatomy

- surface: your content as children; the cursors are drawn over it without catching the pointer
- cursor: an arrow in the person's colour and a flag with their name (and a short note: 'Viewing', 'Editing')
- selection: a rectangle outlined and lightly filled in their colour, their name on its corner
- message: a bubble beside the pointer while they type and for a few seconds after
- your message: press / over the surface, type, Enter sends and Escape closes; it follows your pointer
- a live line for assistive tech: who joined, who left, and messages

## Variants

- **flags**: always, moving (names show while the cursor moves or has a message)

## States

- moving
- still
- idle (dimmed)
- joining
- leaving
- with message
- typing your message

## Keyboard

- / over the focused surface starts your message; Enter sends it, Escape closes it
- Cursors are pictures, not stops; the live line says who joined, who left and what they said

## Motion

Each cursor glides to the latest position on a critically damped spring (updates at 10–20 per second read as one smooth path), with a frame loop that runs only while a cursor is still travelling, so a still room costs nothing. A joining cursor scales in from its tip; a leaving one fades where it was. Name flags slide out as a cursor moves and fold after it rests. Reduced motion: cursors jump to each position and flags stay.

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `people` (required) | `LivePerson[]` | — |  |
| `children` | `ReactNode` | — | The shared surface. |
| `onCursorMove` | `(at: { x: number; y: number } \| null) => void` | — | Your pointer as fractions of the surface (null when it leaves), at most once a frame, for your realtime service to broadcast. |
| `onMessage` | `(text: string) => void` | — | With it, / opens your cursor message. |
| `flags` | `"always" \| "moving"` | — | When names show. Default "always". |
| `label` | `string` | — | What the surface is, for assistive tech. Default "Shared canvas". |
| `className / classNames / style / ref` | `root` | — |  |

## Import

```tsx
import { LiveCursors } from "@/components/live-cursors/live-cursors";
```

## Get it

Live cursors is part of Beamline: 200+ components and 50+ complete screens for React that your coding agent (Claude Code, Codex, Cursor or any MCP client) installs into your app through Beamline's MCP server, as a ready-built package or as plain React source you can change. $49 launch price, one payment, no subscription, lifetime updates, one licence for your whole team. [Get Beamline](https://beamline.io/checkout?pack=complete) · [Connect your agent](https://beamline.io/connect)

## More in Content & display

- [Image compare](https://beamline.io/components/image-compare): Two images in one frame with a divider: drag anywhere, or arrow keys on the handle; horizontal or vertical, with captions.
- [Video player](https://beamline.io/components/video): A video player on the native <video> element: title bar with an external link and close, centre play with ±10 s, scrub, time, volume, speed, captions…
- [Lightbox](https://beamline.io/components/lightbox): A full-screen image viewer: a thumbnail grows into it and shrinks back, arrows and ←/→ step through the set, Esc or a downward drag closes it.
- [File diff](https://beamline.io/components/file-diff): A change to one file as a unified diff: line numbers, tinted lines, only the changed words marked, long unchanged stretches folded; give rows or just…
- [QR Code](https://beamline.io/components/qr-code): A scannable code set as gradient dots with rounded finder rings and an optional centre mark; a new value ripples out from the centre.
- [Slot text](https://beamline.io/components/slot-text): Text and numbers that roll into their new value on reels, digit by digit from the right; other characters fade. Read as plain text by assistive tech.
- [Text reveal](https://beamline.io/components/text-reveal): A headline whose words rise into place once, the first time it scrolls into view; never repeats.
- [Text morph](https://beamline.io/components/text-morph): A short label that becomes its next state letter by letter: shared letters glide into place, new ones arrive, old ones leave.
- [Code block](https://beamline.io/components/code-block): Code to read and copy: highlighted in the system's colours, numbered, marked lines, long files folded behind “Show all”.
- [Inbox list](https://beamline.io/components/inbox-list): Conversations waiting for a person, triaged in place: sender, subject and the first words, time, unread weight, star, labels and attachments, grouped by…
- [Comment thread](https://beamline.io/components/comment-thread): A discussion attached to something: replies, reactions, @mentions, editing and deleting your own, resolve that folds the thread.
- [Timeline](https://beamline.io/components/timeline): What happened, newest first and grouped by day: people with avatars, systems with toned icons, relative times with the exact time on hover, details in…
- [Description list](https://beamline.io/components/description-list): The details of one record as label and value pairs: beside each other or stacked, in as many columns as the room holds; a copy button arrives on the row…
- [Text shimmer](https://beamline.io/components/text-shimmer): Ongoing work said in words (“Thinking…”) with a calm band of light passing across them; stops when inactive.
- [Logo Carousel](https://beamline.io/components/logo-carousel): A wall of logos shown a few at a time: every few seconds the slots turn left to right, each logo leaving upward as the next rises in.
- [Avatar group](https://beamline.io/components/avatar-group): A team in a small space: overlapping faces that name themselves on hover or focus, and “+N” naming the rest.
- [Avatar](https://beamline.io/components/avatar): A person or account in a small space: a photo, or initials on the hue their name always gets; presence dot; circle for people, square for companies.
- [Item](https://beamline.io/components/item): The generic list row: media, title, description, meta and trailing actions; becomes a link or button when interactive.
- [Marker](https://beamline.io/components/marker): A labelled point in a stream: a status event with an icon between messages, or a label such as "Today" between two hairlines.
- [Credit](https://beamline.io/components/credit): "Designed with Beamline" for a site's footer: the Beamline mark and a quiet line, or a small badge. With your referral code, a team's first purchase…
- [Badge](https://beamline.io/components/badge): A short status, category or count label: six tones, an icon or a status dot, two sizes.
- [Kbd](https://beamline.io/components/kbd): Keyboard keys as keycaps, for combinations and sequences (G then A); `mod` resolves to ⌘ or Ctrl per platform, symbols are spoken as words.