Handles

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:

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:

TypeDescription
vertexA primary control point that defines part of the shape's geometry
virtualA secondary handle that isn't a vertex, like the arrow's midpoint bend handle
createA handle for adding new geometry, like inserting a point into a line segment
cloneA 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:

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:

FieldDescription
initialThe shape as it was when the drag started
isPreciseWhether the user is dragging precisely, for example by holding Alt
isCreatingShapeWhether 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:

MethodWhen it's called
onHandleDragStartWhen the user starts dragging
onHandleDragEndWhen the user releases the handle
onHandleDragCancelWhen 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.

{
	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:

ValueBehavior
'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:

{
	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:

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:

PropertyDescription
outlineCustom outline geometry for snapping (default: shape geometry)
pointsKey points to snap to (default: none)
getSelfSnapOutlineReturns outline for self-snapping given a handle
getSelfSnapPointsReturns points for self-snapping given a handle

Complete example

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

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

Prev
Groups
Next
Highlighting