Handles - Tldraw — ContextQMD

In tldraw, handles are interactive control points on shapes that let users manipulate shape geometry. Arrows have handles at their endpoints, lines have handles at each vertex, and notes have clone handles for quick duplication.

Handle basics

Handles appear when a single shape is selected with the select tool. Each handle has a position, type, and optional snapping behavior. You define handles by implementing ShapeUtil#getHandles on your ShapeUtil:

tsx

import { ShapeUtil, TLHandle, ZERO_INDEX_KEY } from 'tldraw'

class MyShapeUtil extends ShapeUtil<MyShape> {
	// ...

	override getHandles(shape: MyShape): TLHandle[] {
		return [
			{
				id: 'point',
				type: 'vertex',
				index: ZERO_INDEX_KEY,
				x: shape.props.pointX,
				y: shape.props.pointY,
			},
		]
	}
}

Handle coordinates are in the shape's local coordinate system, where (0, 0) is the shape's top-left corner.

Handle types

There are four handle types:

Type	Description
`vertex`	A primary control point that defines part of the shape's geometry
`virtual`	A secondary handle that isn't a vertex, like the arrow's midpoint bend handle
`create`	A handle for adding new geometry, like inserting a point into a line segment
`clone`	A handle for duplicating the shape, used by notes for quick adjacent copies

Most custom shapes use vertex handles. The arrow shape uses a virtual handle for its midpoint, and the line shape uses create handles to let users add points between vertices.

Responding to handle drags

When a user drags a handle, tldraw calls ShapeUtil#onHandleDrag with the updated handle position. Return a partial of the shape with the changed props:

tsx

import { ShapeUtil, TLHandleDragInfo } from 'tldraw'

class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	// ...

	override onHandleDrag(shape: SpeechBubbleShape, { handle }: TLHandleDragInfo<SpeechBubbleShape>) {
		return {
			props: { tailX: handle.x, tailY: handle.y },
		}
	}
}

The handle in TLHandleDragInfo carries the new x and y after any snapping. The info object also has these fields:

Field	Description
`initial`	The shape as it was when the drag started
`isPrecise`	Whether the user is dragging precisely, for example by holding Alt
`isCreatingShape`	Whether the handle drag is part of creating the shape, like a new arrow

Lifecycle callbacks

For more control over handle interactions, implement these additional methods:

Method	When it's called
`onHandleDragStart`	When the user starts dragging
`onHandleDragEnd`	When the user releases the handle
`onHandleDragCancel`	When the drag is cancelled (escape)

Handle snapping

Handles can snap to other shapes' geometry. Set snapType on the handle. Snapping engages while the user holds Ctrl (Cmd on Mac); with snap mode turned on in preferences, it's the reverse: snapping is on and Ctrl disables it. The older canSnap: true flag is deprecated; use snapType: 'point' instead. See Snapping for how snapping works across the editor.

tsx

{
	id: 'end',
	type: 'vertex',
	index: ZERO_INDEX_KEY,
	x: shape.props.endX,
	y: shape.props.endY,
	snapType: 'point', // Snap to points on other shapes
}

The snapType options are:

Value	Behavior
`'point'`	Snaps to key points on other shapes first, then to the nearest point on their outlines
`'align'`	Snaps the handle's x and y independently to the x and y of key points on other shapes

Angle snapping

When the user holds Shift while dragging, handles snap to 15-degree angles. By default, the angle is measured relative to the next vertex handle on the shape. You can snap relative to a specific handle by setting snapReferenceHandleId:

tsx

{
	id: 'controlPoint',
	type: 'vertex',
	index: getIndexAbove(ZERO_INDEX_KEY),
	x: shape.props.cpX,
	y: shape.props.cpY,
	snapType: 'align',
	snapReferenceHandleId: 'start', // Angle snaps relative to 'start' handle
}

Bezier curves use this so control points snap to angles relative to their associated endpoint.

Custom snap geometry

By default, handles snap to a shape's outline (its geometry) and to no key points. Override ShapeUtil#getHandleSnapGeometry to customize what handles snap to:

tsx

import { HandleSnapGeometry, ShapeUtil } from 'tldraw'

class BezierCurveUtil extends ShapeUtil<BezierCurveShape> {
	// ...

	override getHandleSnapGeometry(shape: BezierCurveShape): HandleSnapGeometry {
		return {
			// Points other shapes' handles can snap to
			points: [shape.props.start, shape.props.end],

			// Points this shape's own handles can snap to (for self-snapping)
			getSelfSnapPoints: (handle) => {
				if (handle.id === 'controlPoint') {
					return [shape.props.start, shape.props.end]
				}
				return []
			},
		}
	}
}

The HandleSnapGeometry object has these properties:

Property	Description
`outline`	Custom outline geometry for snapping (default: shape geometry)
`points`	Key points to snap to (default: none)
`getSelfSnapOutline`	Returns outline for self-snapping given a handle
`getSelfSnapPoints`	Returns points for self-snapping given a handle

Complete example

Here's a speech bubble shape with a draggable tail handle:

tsx

import {
	Polygon2d,
	ShapeUtil,
	TLHandle,
	TLHandleDragInfo,
	TLShape,
	Vec,
	ZERO_INDEX_KEY,
} from 'tldraw'

const SPEECH_BUBBLE_TYPE = 'speech-bubble'

declare module 'tldraw' {
	export interface TLGlobalShapePropsMap {
		[SPEECH_BUBBLE_TYPE]: { w: number; h: number; tailX: number; tailY: number }
	}
}

type SpeechBubbleShape = TLShape<typeof SPEECH_BUBBLE_TYPE>

class SpeechBubbleUtil extends ShapeUtil<SpeechBubbleShape> {
	static override type = SPEECH_BUBBLE_TYPE

	getDefaultProps(): SpeechBubbleShape['props'] {
		return { w: 200, h: 100, tailX: 100, tailY: 150 }
	}

	getGeometry(shape: SpeechBubbleShape) {
		const { w, h, tailX, tailY } = shape.props
		return new Polygon2d({
			points: [
				new Vec(0, 0),
				new Vec(w, 0),
				new Vec(w, h),
				new Vec(w * 0.7, h),
				new Vec(tailX, tailY),
				new Vec(w * 0.3, h),
				new Vec(0, h),
			],
			isFilled: true,
		})
	}

	override getHandles(shape: SpeechBubbleShape): TLHandle[] {
		return [
			{
				id: 'tail',
				type: 'vertex',
				label: 'Move tail', // Accessible name for the handle
				index: ZERO_INDEX_KEY,
				x: shape.props.tailX,
				y: shape.props.tailY,
			},
		]
	}

	override onHandleDrag(shape: SpeechBubbleShape, { handle }: TLHandleDragInfo<SpeechBubbleShape>) {
		return {
			props: { tailX: handle.x, tailY: handle.y },
		}
	}

	component(shape: SpeechBubbleShape) {
		const geometry = this.getGeometry(shape)
		return (
			<svg className="tl-svg-container">
				<path d={geometry.getSvgPathData()} fill="white" stroke="black" />
			</svg>
		)
	}

	getIndicatorPath(shape: SpeechBubbleShape) {
		const geometry = this.getGeometry(shape)
		return new Path2D(geometry.getSvgPathData())
	}
}

Reading handles

Use Editor#getShapeHandles to get the handles for any shape:

const handles = editor.getShapeHandles(shape)
if (handles) {
	for (const handle of handles) {
		console.log(handle.id, handle.x, handle.y)
	}
}

Returns undefined if the shape doesn't have handles.

Examples

Custom shape with handles — A speech bubble shape with a draggable tail handle
Cubic bezier curve shape — Multiple handles with custom snapping and control point behavior