Cursors

The cursor system controls what cursor users see when interacting with the canvas. The current cursor is stored in instance state and changes automatically as users hover over different elements or use different tools. You can also set the cursor manually for custom tools.

Cursor state

The cursor state is a TLCursor: a TLCursorType and a rotation angle. Access it through Editor.getInstanceState:

const { type, rotation } = editor.getInstanceState().cursor

The type determines the visual appearance—like 'default', 'grab', or 'nwse-resize'. The rotation is an angle in radians that rotates the cursor icon. Rotation is mainly used for resize and rotate cursors so they align with the shape being manipulated.

Cursor types

tldraw supports these cursor types:

Static cursors like default, pointer, and grab are prerendered SVG cursors defined as CSS custom properties in tldraw's stylesheet (--tl-cursor-default, --tl-cursor-grab, and so on). Dynamic cursors like the resize and rotate types are generated at runtime as SVGs with the current rotation applied. The canvas reads the result from the --tl-cursor variable.

Setting the cursor

Use Editor.setCursor to change the cursor:

editor.setCursor({ type: 'cross', rotation: 0 })

You can update just the type or just the rotation—the other property keeps its current value:

// Change only the type
editor.setCursor({ type: 'grab' })

// Change only the rotation
editor.setCursor({ rotation: Math.PI / 4 })

Cursor rotation

Rotation is specified in radians. When users resize or rotate shapes that are themselves rotated, the cursor rotates to match:

// Get the selection's rotation and apply it to a resize cursor
const selectionRotation = editor.getSelectionRotation()
editor.setCursor({
	type: 'nwse-resize',
	rotation: selectionRotation,
})

This keeps the cursor aligned with the shape's edges rather than the screen axes. The default tools handle cursor rotation automatically. You only need to set it manually for custom tools.

Cursors in custom tools

Custom tools typically set the cursor when entering a state and reset it when exiting:

import { StateNode } from 'tldraw'

export class MyCustomTool extends StateNode {
	static override id = 'my-tool'

	override onEnter() {
		this.editor.setCursor({ type: 'cross', rotation: 0 })
	}

	override onExit() {
		this.editor.setCursor({ type: 'default', rotation: 0 })
	}
}

For tools with child states, each state can set its own cursor. A drawing state might use 'cross', while a dragging state uses 'grabbing'.

Cursor colors

Dynamic cursors (resize and rotate types) receive the active theme's cursor color for the current color mode: black in the default light theme, white in the default dark theme. The built-in SVGs use fixed black and white fills for contrast, so this color only shows in custom cursor SVGs.

Collaborator cursors

In multiplayer sessions, each user's cursor appears on other users' canvases. These remote cursors use the user's presence color—a randomly assigned color from the user color palette.

User color palette

When a user first loads tldraw, they're assigned a random color from the built-in USER_COLORS palette:

const USER_COLORS = [
	'#FF802B',
	'#EC5E41',
	'#F2555A',
	'#F04F88',
	'#E34BA9',
	'#BD54C6',
	'#9D5BD2',
	'#7B66DC',
	'#02B1CC',
	'#11B3A3',
	'#39B178',
	'#55B467',
]

You can read or change a user's color through user preferences:

// Get the user's color
const color = editor.user.getColor()

// Set a specific color
editor.user.updateUserPreferences({ color: '#FF802B' })

Rendering collaborator cursors

Remote cursors render as DOM elements in a dedicated layer stacked above the canvas and below the UI panels. Each visible collaborator gets a cursor showing:

• The cursor arrow in the user's color
• The user's name as a label next to the cursor
• Any active chat message in a bubble

A collaborator whose cursor is outside your viewport shows as a small hint arrow clamped to the viewport edge, pointing toward them. CollaboratorHintOverlayUtil draws the hints on the overlay canvas rather than as DOM elements.

To customize the cursor, pass your own component via the components prop's CollaboratorCursor slot (see DefaultCursor and TLCursorProps):

import { TLCursorProps, Tldraw } from 'tldraw'
import 'tldraw/tldraw.css'

function CustomCollaboratorCursor({ point, color, name, zoom }: TLCursorProps) {
	if (!point) return null
	return (
		<div
			style={{
				position: 'absolute',
				// The layer is scaled by the camera, so counter-scale by 1 / zoom to keep the
				// cursor a constant on-screen size (the default components do the same).
				transform: `translate(${point.x}px, ${point.y}px) scale(${1 / zoom})`,
				transformOrigin: 'top left',
				pointerEvents: 'none',
			}}
		>
			{/* A dot instead of the default arrow */}
			<div style={{ width: 16, height: 16, borderRadius: '50%', backgroundColor: color }} />
			{name && <div style={{ color }}>{name}</div>}
		</div>
	)
}

export default function App() {
	return (
		<div style={{ position: 'fixed', inset: 0 }}>
			<Tldraw components={{ CollaboratorCursor: CustomCollaboratorCursor }} />
		</div>
	)
}

Cursor position in presence

Collaborator cursor positions are stored in presence records (TLInstancePresence). The cursor field includes position, type, and rotation:

{
  cursor: {
    x: number
    y: number
    type: TLCursorType
    rotation: number
  } | null
}

The editor automatically broadcasts cursor position updates to other users in the same room. cursor is null only when presence hasn't been populated yet or a custom presence derivation omits it. The editor hides a collaborator's cursor when it's outside your viewport or the user has been inactive.

Related articles

• Cursor chat - Send ephemeral chat messages at the cursor position
• Tools - Learn how tools handle input and set cursors
• Collaboration - User presence and multiplayer features
• User preferences - Manage user colors and other preferences
• Overlay utils - Canvas overlays, including the collaborator cursor hint overlay

Related examples

• Custom tool - Build a custom tool with cursor handling
• User presence - Display collaborator cursors and presence