feat(editor): add selectLockedShapes option (tldraw#8860)

Adds a new `selectLockedShapes` option to `TldrawOptions` that, when
enabled, lets users select locked shapes with a left click (and via
brush or scribble selection). The editor's existing lock guards still
prevent moving, resizing, editing, or deleting locked shapes, so the
option enables inspection without unlocking.

When `selectLockedShapes: true`:
- `getHitShapeOnCanvasPointerDown` passes `hitLocked: true`
- `Idle.onPointerDown` no longer routes left clicks on locked shapes to
`pointing_canvas`
- `Brushing` and `ScribbleBrushing` include locked shapes
- Hover detection (`updateHoveredShapeId`) treats locked shapes as
hoverable
- `selectOnCanvasPointerUp` allows locked shapes through

When `selectLockedShapes` is `false` (default), behavior is unchanged.

Closes tldraw#8548

### Change type

- [ ] `bugfix`
- [ ] `improvement`
- [x] `feature`
- [ ] `api`
- [ ] `other`

### Test plan

1. Set `<Tldraw options={{ selectLockedShapes: true }} />` in an example
app.
2. Create a shape, lock it, and click it — it should become selected and
show selection bounds.
3. Try to drag or resize it — nothing should move (lock still applies).
4. Brush over the locked shape with the select tool — it should be
included in the brush selection.
5. Alt-drag (scribble select) over the locked shape — it should also be
included.
6. With the option set to `false` (default), confirm left-clicking a
locked shape still falls through to the canvas, matching the previous
behavior.

- [x] Unit tests
- [ ] End to end tests

 ### API changes

- Add a new `selectLockedShapes` option to `TldrawOptions` (and to
`defaultTldrawOptions`). When `false` (default), left-clicking a locked
shape is treated as a click on the canvas; only right-click selects it.
When `true`, locked shapes can be selected via left-click and included
in brush and scribble selections, but the editor's lock guards still
prevent moving, resizing, editing, or deleting them.


### Release notes

- Added a `selectLockedShapes` option to `TldrawOptions`. When enabled,
locked shapes can be selected with left click and brush/scribble
selection while remaining protected from edits, moves, and deletes.

---------

Co-authored-by: angrycaptain19 <53473467+angrycaptain19@users.noreply.github.com>

Author: steveruizok

apps/examples/src/examples/editor-api/locked-shapes/LockedShapesExample.tsx

@@ -1,3 +1,4 @@
+import { useState } from 'react'
 import { createShapeId, Tldraw, TldrawUiButton, TLShapeId, toRichText, useEditor } from 'tldraw'
 import 'tldraw/tldraw.css'
 
@@ -13,7 +14,20 @@ const TEMPLATE_IDS: TLShapeId[] = [
 function ControlPanel() {
 	const editor = useEditor()
 
-	// [3] Update locked shapes using ignoreShapeLock option
+	// [3] Local state mirrors editor.options.selectLockedShapes for the UI.
+	// The option is readonly at the type level but the editor stores a copy
+	// internally that the SelectTool reads live on every interaction — so
+	// mutating the underlying field flips behaviour immediately, without a
+	// remount.
+	const [selectLocked, setSelectLocked] = useState(editor.options.selectLockedShapes)
+
+	const toggleSelectLocked = () => {
+		const next = !selectLocked
+		;(editor.options as { selectLockedShapes: boolean }).selectLockedShapes = next
+		setSelectLocked(next)
+	}
+
+	// [4] Update locked shapes using ignoreShapeLock option
 	// Without ignoreShapeLock: true, these updates would be blocked
 	const handleScatter = () => {
 		editor.run(
@@ -46,7 +60,21 @@ function ControlPanel() {
 	}
 
 	return (
-		<div className="tlui-menu">
+		<div className="tlui-menu" style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
+			<label
+				style={{
+					display: 'flex',
+					alignItems: 'center',
+					gap: 6,
+					fontSize: 13,
+					cursor: 'pointer',
+					userSelect: 'none',
+				}}
+				title="When on, left-click and brush selection include locked shapes."
+			>
+				<input type="checkbox" checked={selectLocked} onChange={toggleSelectLocked} />
+				Allow selecting locked shapes
+			</label>
 			<TldrawUiButton type="normal" onClick={handleScatter}>
 				Scatter
 			</TldrawUiButton>
@@ -61,7 +89,7 @@ const components = {
 	TopPanel: ControlPanel,
 }
 
-// [4]
+// [5]
 export default function LockedShapesExample() {
 	return (
 		<div className="tldraw__editor">
@@ -74,7 +102,7 @@ export default function LockedShapesExample() {
 						return
 					}
 
-					// [5] Create locked template shapes
+					// [6] Create locked template shapes
 					const shapeProps = {
 						geo: 'rectangle' as const,
 						w: 130,
@@ -92,7 +120,7 @@ export default function LockedShapesExample() {
 						{ id: TEMPLATE_IDS[3], type: 'geo', x: 250, y: 250, props: shapeProps },
 					])
 
-					// [6] Lock them immediately
+					// [7] Lock them immediately
 					editor.toggleLock(TEMPLATE_IDS)
 					editor.zoomToFit({ animation: { duration: 0 } })
 				}}
@@ -102,27 +130,46 @@ export default function LockedShapesExample() {
 }
 
 /*
-This example demonstrates the key distinction between locked shapes and programmatic updates:
+This example demonstrates two ways the editor distinguishes user interaction
+from programmatic mutation on locked shapes:
 
-Locked shapes prevent ALL user interaction (dragging, deleting, etc.), but programs can still
-modify them using the ignoreShapeLock option. This is useful for shapes that should be fixed
-in place by the user but need to be repositioned programmatically.
+1. `editor.run(fn, { ignoreShapeLock: true })` bypasses the lock guard for
+   the duration of the callback, so the Scatter / Reset buttons can move
+   shapes the user can't drag.
+2. `editor.options.selectLockedShapes` controls whether locked shapes can be
+   *selected* (via left-click, brush select, scribble select). The lock
+   guards on moving, resizing, editing, and deleting still apply — selection
+   is the only thing this option unlocks.
 
 [1] Pre-defined shape IDs so we can reference them later.
 
-[2] Control panel with action buttons.
+[2] Control panel with the new toggle plus the existing action buttons.
+
+[3] Local React state mirrors the live editor option. The option is
+`readonly` at the type level (it's intended as initial editor config) but
+the editor stores a single mutable copy that the SelectTool reads on every
+relevant pointer event. Mutating the field changes behaviour immediately
+without remounting. The cast through `{ selectLockedShapes: boolean }`
+isolates the type relaxation to one line.
 
-[3] Both buttons use editor.run() with { ignoreShapeLock: true } to bypass the lock constraint.
-This option allows programmatic updates even though user interactions on these shapes are blocked.
+[4] Both buttons use `editor.run()` with `{ ignoreShapeLock: true }` to
+bypass the lock constraint. This option allows programmatic updates even
+though user interactions on these shapes are blocked.
 
-[4] The main component sets up the editor.
+[5] The main component sets up the editor.
 
-[5] On mount, we create a 2x2 grid of template shapes.
+[6] On mount, we create a 2x2 grid of template shapes.
 
-[6] We immediately lock them with toggleLock(). The key behavior: users cannot move or delete
-these shapes, but the Scatter/Reset buttons can still reposition them programmatically.
+[7] We immediately lock them with `toggleLock()`. The key behavior: users
+cannot move or delete these shapes, but the Scatter / Reset buttons can
+still reposition them programmatically.
 
 Try it:
-- Try dragging any template shape (won't work - they're locked by the user interface)
-- Click Scatter or Reset to see how programmatic updates work with ignoreShapeLock: true
+- Default: try left-clicking a template shape — nothing happens (locked
+  shapes aren't selectable). Right-click still selects.
+- Flip the "Allow selecting locked shapes" toggle on, then left-click or
+  brush-select across a template shape — it gets selected. Try to drag it
+  by the handles — the lock guard still prevents the move.
+- Click Scatter or Reset to see how programmatic updates work with
+  `ignoreShapeLock: true` regardless of the toggle.
 */

packages/editor/api-report.api.md

@@ -779,6 +779,7 @@ export const defaultTldrawOptions: {
     readonly onClipboardPasteRaw: undefined;
     readonly quickZoomPreservesScreenBounds: true;
     readonly rightClickPanning: true;
+    readonly selectLockedShapes: false;
     readonly snapThreshold: 8;
     readonly spacebarPanning: true;
     readonly temporaryAssetPreviewLifetimeMs: 180000;
@@ -3841,6 +3842,7 @@ export interface TldrawOptions {
     onClipboardPasteRaw?(info: TLClipboardPasteRawInfo): false | void;
     readonly quickZoomPreservesScreenBounds: boolean;
     readonly rightClickPanning: boolean;
+    readonly selectLockedShapes: boolean;
     readonly snapThreshold: number;
     readonly spacebarPanning: boolean;
     readonly temporaryAssetPreviewLifetimeMs: number;

packages/editor/src/lib/options.ts

@@ -171,6 +171,13 @@ export interface TldrawOptions {
 	 * The distance (in screen pixels) at which shapes snap to guides and other shapes.
 	 */
 	readonly snapThreshold: number
+	/**
+	 * Whether locked shapes can be selected with a left click. When false (default), left-clicking
+	 * a locked shape is treated as a click on the canvas — only right-click selects it. When true,
+	 * locked shapes can be selected via left click and included in brush and scribble selections,
+	 * but the editor's lock guards still prevent moving, resizing, editing, or deleting them.
+	 */
+	readonly selectLockedShapes: boolean
 	/**
 	 * Options for the editor's camera. These are the initial camera options.
 	 * Use {@link Editor.setCameraOptions} to update camera options at runtime.
@@ -335,6 +342,7 @@ export const defaultTldrawOptions = {
 	rightClickPanning: true,
 	zoomToFitPadding: 128,
 	snapThreshold: 8,
+	selectLockedShapes: false,
 	camera: DEFAULT_CAMERA_OPTIONS,
 	text: {},
 	deepLinks: undefined,

packages/tldraw/src/lib/tools/SelectTool/childStates/Brushing.ts

@@ -52,11 +52,14 @@ export class Brushing extends StateNode {
 			return
 		}
 
+		const selectLockedShapes = editor.options.selectLockedShapes
 		this.excludedShapeIds = new Set(
 			editor
 				.getCurrentPageShapes()
 				.filter(
-					(shape) => editor.isShapeOfType(shape, 'group') || editor.isShapeOrAncestorLocked(shape)
+					(shape) =>
+						editor.isShapeOfType(shape, 'group') ||
+						(!selectLockedShapes && editor.isShapeOrAncestorLocked(shape))
 				)
 				.map((shape) => shape.id)
 		)

packages/tldraw/src/lib/tools/SelectTool/childStates/Idle.ts

@@ -87,7 +87,7 @@ export class Idle extends StateNode {
 				// Check to see if we hit any shape under the pointer; if so,
 				// handle this as a pointer down on the shape instead of the canvas
 				const hitShape = getHitShapeOnCanvasPointerDown(this.editor)
-				if (hitShape && !hitShape.isLocked) {
+				if (hitShape && (this.editor.options.selectLockedShapes || !hitShape.isLocked)) {
 					this.onPointerDown({
 						...info,
 						shape: hitShape,
@@ -184,7 +184,7 @@ export class Idle extends StateNode {
 			case 'shape': {
 				const { shape } = info
 
-				if (this.editor.isShapeOrAncestorLocked(shape)) {
+				if (!this.editor.options.selectLockedShapes && this.editor.isShapeOrAncestorLocked(shape)) {
 					this.parent.transition('pointing_canvas', info)
 					break
 				}
@@ -242,7 +242,7 @@ export class Idle extends StateNode {
 						if (
 							hoveredShape &&
 							!this.editor.getSelectedShapeIds().includes(hoveredShape.id) &&
-							!hoveredShape.isLocked
+							(this.editor.options.selectLockedShapes || !hoveredShape.isLocked)
 						) {
 							this.onPointerDown({
 								...info,

packages/tldraw/src/lib/tools/SelectTool/childStates/ScribbleBrushing.ts

@@ -123,11 +123,12 @@ export class ScribbleBrushing extends StateNode {
 		for (let i = 0, n = shapes.length; i < n; i++) {
 			shape = shapes[i]
 
-			// If the shape is a group or is already selected or locked, don't select it
+			// If the shape is a group or is already selected, don't select it.
+			// Also skip locked shapes unless the selectLockedShapes option is enabled.
 			if (
 				editor.isShapeOfType(shape, 'group') ||
 				newlySelectedShapeIds.has(shape.id) ||
-				editor.isShapeOrAncestorLocked(shape)
+				(!editor.options.selectLockedShapes && editor.isShapeOrAncestorLocked(shape))
 			) {
 				continue
 			}

packages/tldraw/src/lib/tools/selection-logic/getHitShapeOnCanvasPointerDown.ts

@@ -13,6 +13,7 @@ export function getHitShapeOnCanvasPointerDown(
 		editor.getShapeAtPoint(currentPagePoint, {
 			hitInside: false,
 			hitLabels,
+			hitLocked: editor.options.selectLockedShapes,
 			margin: editor.options.hitTestMargin / zoomLevel,
 			renderingOnly: true,
 		}) ??

packages/tldraw/src/lib/tools/selection-logic/selectOnCanvasPointerUp.ts

@@ -9,12 +9,14 @@ export function selectOnCanvasPointerUp(
 	const { shiftKey, altKey, accelKey } = info
 	const additiveSelectionKey = shiftKey || accelKey
 
+	const selectLockedShapes = editor.options.selectLockedShapes
 	const hitShape = editor.getShapeAtPoint(currentPagePoint, {
 		hitInside: false,
 		margin: editor.options.hitTestMargin / editor.getZoomLevel(),
 		hitLabels: true,
+		hitLocked: selectLockedShapes,
 		renderingOnly: true,
-		filter: (shape) => !shape.isLocked,
+		filter: (shape) => selectLockedShapes || !shape.isLocked,
 	})
 
 	// Note at the start: if we select a shape that is inside of a group,

packages/tldraw/src/lib/tools/selection-logic/updateHoveredShapeId.ts

@@ -25,6 +25,7 @@ function getShapeToHover(editor: Editor): TLShapeId | null {
 	const hitShape = editor.getShapeAtPoint(editor.inputs.getCurrentPagePoint(), {
 		hitInside: false,
 		hitLabels: false,
+		hitLocked: editor.options.selectLockedShapes,
 		margin: editor.options.hitTestMargin / editor.getZoomLevel(),
 		renderingOnly: true,
 	})

packages/tldraw/src/test/commands/lockShapes.test.ts

@@ -297,3 +297,67 @@ it('works when forced', () => {
 	)
 	expect(editor.getShape(myShapeId)).toBeUndefined()
 })
+
+describe('When the selectLockedShapes option is enabled', () => {
+	let lockEditor: TestEditor
+
+	beforeEach(() => {
+		lockEditor = new TestEditor({ options: { selectLockedShapes: true } })
+		lockEditor.createShapes([
+			{
+				id: ids.lockedShapeA,
+				type: 'geo',
+				x: 0,
+				y: 0,
+				isLocked: true,
+				props: { fill: 'solid' },
+			},
+			{ id: ids.unlockedShapeA, type: 'geo', x: 200, y: 200, isLocked: false },
+		])
+	})
+
+	it('Can be selected by clicking', () => {
+		const shape = lockEditor.getShape(ids.lockedShapeA)!
+
+		lockEditor
+			.pointerDown(10, 10, { target: 'shape', shape })
+			.expectToBeIn('select.pointing_shape')
+			.pointerUp()
+			.expectToBeIn('select.idle')
+		expect(lockEditor.getSelectedShapeIds()).toEqual([ids.lockedShapeA])
+	})
+
+	it('Can be selected by left-clicking on the canvas over the shape', () => {
+		lockEditor
+			.pointerDown(10, 10, { target: 'canvas' })
+			.expectToBeIn('select.pointing_shape')
+			.pointerUp()
+			.expectToBeIn('select.idle')
+		expect(lockEditor.getSelectedShapeIds()).toEqual([ids.lockedShapeA])
+	})
+
+	it('Can be selected by brushing', () => {
+		lockEditor
+			.pointerDown(-10, -10, { target: 'canvas' })
+			.pointerMove(250, 250)
+			.expectToBeIn('select.brushing')
+			.pointerUp()
+		expect(lockEditor.getSelectedShapeIds()).toEqual(
+			expect.arrayContaining([ids.lockedShapeA, ids.unlockedShapeA])
+		)
+	})
+
+	it('Still cannot be moved or mutated while selected', () => {
+		const shape = lockEditor.getShape(ids.lockedShapeA)!
+		const xBefore = shape.x
+
+		lockEditor.pointerDown(10, 10, { target: 'shape', shape }).pointerMove(50, 50).pointerUp()
+
+		expect(lockEditor.getShape(ids.lockedShapeA)!.x).toBe(xBefore)
+	})
+
+	it('Still cannot be deleted via deleteShapes', () => {
+		lockEditor.deleteShapes([ids.lockedShapeA])
+		expect(lockEditor.getShape(ids.lockedShapeA)).not.toBeUndefined()
+	})
+})