Element Binding System

Relevant source files

• packages/common/src/utils.ts
• packages/element/src/binding.ts
• packages/element/src/bounds.ts
• packages/element/src/collision.ts
• packages/element/src/cropElement.ts
• packages/element/src/distance.ts
• packages/element/src/utils.ts
• packages/excalidraw/actions/actionBoundText.tsx
• packages/excalidraw/actions/actionFlip.ts
• packages/excalidraw/actions/actionProperties.tsx
• packages/excalidraw/data/restore.ts
• packages/excalidraw/fonts/Fonts.ts
• packages/excalidraw/lasso/utils.ts
• packages/excalidraw/renderer/helpers.ts
• packages/excalidraw/tests/helpers/ui.ts
• packages/math/src/curve.ts
• packages/math/src/rectangle.ts
• packages/math/src/utils.ts
• packages/math/src/vector.ts
• packages/math/tests/curve.test.ts

Purpose and Scope

The Element Binding System manages the attachment relationships between elements in Excalidraw. This system handles two primary binding types: arrow-to-element bindings (connecting arrow endpoints to shapes) and text-to-container bindings (attaching text elements inside shapes). The system maintains binding metadata, detects eligible binding targets, updates bound elements during transformations, and repairs broken bindings during data restoration.

For information about element creation and lifecycle, see Element Types and Creation. For details on element transformations, see Element Properties and Transformations.

---

Binding Types and Data Structures

Binding Type Hierarchy

Sources: packages/element/src/binding.ts1-100 packages/excalidraw/data/restore.ts52-86

Binding Data Structures

Structure	Properties	Usage
PointBinding	elementId, focus, gap	Standard arrow-to-element binding
FixedPointBinding	extends PointBinding + fixedPoint: [x, y]	Elbow arrow bindings with fixed attachment points
boundElements	Array of {id: string, type: 'arrow'|'text'}	Tracks elements bound to a container
containerId	string | null	Text element reference to its container

Sources: packages/element/src/binding.ts70-85 packages/excalidraw/data/restore.ts60-66

---

Arrow-to-Element Binding

Binding Detection Flow

Sources: packages/element/src/binding.ts97-105 packages/element/src/binding.ts574-658

Binding Parameters

The PointBinding structure stores three key parameters:

• elementId: The ID of the element being bound to
• focus: Normalized position along the element's border (-1 to 1), calculated by determineFocusDistance() packages/element/src/binding.ts896-980
• gap: Distance from arrow endpoint to element border, constrained by maxBindingGap() packages/element/src/binding.ts982-992

For elbow arrows, FixedPointBinding adds:

• fixedPoint: Absolute [x, y] coordinates of the attachment point, calculated by calculateFixedPointForElbowArrowBinding() packages/element/src/binding.ts1102-1249

Sources: packages/element/src/binding.ts480-528 packages/element/src/binding.ts704-734

Binding and Unbinding Operations

The system ensures bidirectional consistency:

1. Arrow stores startBinding/endBinding with target element ID
2. Target element stores arrow ID in its boundElements array
3. Updates to either side trigger corresponding updates on the other side

Sources: packages/element/src/binding.ts124-217 packages/element/src/binding.ts480-528 packages/element/src/binding.ts560-572

Binding During Element Dragging

Drag Type	Strategy	Implementation
Arrow endpoints	Re-evaluate bindings for dragged endpoints	getBindingStrategyForDraggingArrowEndpoints() packages/element/src/binding.ts243-279
Arrow shaft	Keep bindings if still close to original elements	getBindingStrategyForDraggingArrowOrJoints() packages/element/src/binding.ts281-322
Elbow arrows	No rebinding during drag	Returns ["keep", "keep"] packages/element/src/binding.ts289-291

Sources: packages/element/src/binding.ts324-353

---

Text-to-Container Binding

Text Binding Structure

Sources: packages/excalidraw/actions/actionBoundText.tsx1-221 packages/element/src/textElement.ts1-50

Binding Lifecycle

The text binding lifecycle follows these steps:

1. Creation: actionBindText validates that exactly one text element and one compatible container are selected packages/excalidraw/actions/actionBoundText.tsx108-138

2. Binding: Sets textElement.containerId and adds text reference to container.boundElements packages/excalidraw/actions/actionBoundText.tsx155-167

3. Positioning: computeBoundTextPosition() calculates centered position within container packages/element/src/textElement.ts400-500

4. Resizing: redrawTextBoundingBox() adjusts text dimensions to fit container with padding packages/element/src/textElement.ts600-700

5. Maintenance: handleBindTextResize() updates container dimensions when text changes packages/element/src/textElement.ts800-900

Sources: packages/excalidraw/actions/actionBoundText.tsx53-105 packages/excalidraw/actions/actionBoundText.tsx139-180

Text Container Constraints

Sources: packages/excalidraw/actions/actionBoundText.tsx222-300 packages/element/src/textElement.ts200-350

---

Binding Eligibility and Detection

Eligibility Criteria

The getHoveredElementForBinding() function determines which element (if any) should be bound to at a given pointer position:

Sources: packages/element/src/binding.ts574-658 packages/element/src/binding.ts660-702

Border Testing

The bindingBorderTest() function checks if a point is within the binding activation distance of an element's border:

• Threshold: FIXED_BINDING_DISTANCE (5 pixels) packages/element/src/binding.ts107
• Fullshape mode: For solid filled elements, entire area is valid (not just border)
• Frame elements: Fullshape disabled to allow binding to frame children
• Distance calculation: Uses distanceToElement() for precise border distance

Sources: packages/element/src/binding.ts1251-1290 packages/element/src/distance.ts29-53

---

Binding Maintenance and Updates

Update Triggers

Bound elements must be updated when their bound targets change:

Sources: packages/element/src/binding.ts736-859 packages/element/src/binding.ts861-878

Binding Update Algorithm

The updateBoundElements() function follows this algorithm for each bound arrow:

1. Check if update needed: doesNeedUpdate() verifies the arrow binds to the changed element packages/element/src/binding.ts880-888

2. Adjust gap for scaling: If container was resized, maybeCalculateNewGapWhenScaling() proportionally adjusts binding gap packages/element/src/binding.ts1292-1316

3. Calculate new point: updateBoundPoint() computes new arrow endpoint position based on updated binding packages/element/src/binding.ts1318-1377

4. Update arrow geometry: LinearElementEditor.movePoints() updates arrow points and bound text position packages/element/src/binding.ts845-852

5. Handle bound text: If arrow has bound text, handleBindTextResize() repositions it packages/element/src/binding.ts854-857

Sources: packages/element/src/binding.ts738-858

Simultaneous Updates

When multiple elements are updated simultaneously (e.g., during group transformations), the system optimizes binding updates:

• Tracking: simultaneouslyUpdatedElementIds set identifies elements being moved together packages/element/src/binding.ts752-754
• Skip geometry updates: If bound arrow is also being moved, only update binding metadata without recalculating points packages/element/src/binding.ts803-806
• Prevent double updates: Avoids redundant calculations when both arrow and target move together

Sources: packages/element/src/binding.ts890-894 packages/element/src/binding.ts742-763

---

Elbow Arrow Fixed Point Bindings

Fixed Point Calculation

Elbow arrows use FixedPointBinding with absolute attachment coordinates instead of relative focus values:

Sources: packages/element/src/binding.ts1102-1249 packages/excalidraw/data/restore.ts124-156

Fixed Point vs Standard Binding

Aspect	Standard PointBinding	FixedPointBinding (Elbow)
Position storage	Relative focus (-1 to 1)	Absolute fixedPoint [x, y]
Attachment	Calculated from focus along border	Fixed to specific coordinates
Updating	Recalculate from focus on changes	Update routing but keep fixedPoint
Snapping	Not snapped	Snapped to grid/edges/midpoints
Repair	Use repairBinding()	Use normalizeFixedPoint()

Sources: packages/element/src/binding.ts469-478 packages/excalidraw/data/restore.ts136-148

Elbow Arrow Binding Rules

Elbow arrows have special binding behavior:

• No drag rebinding: When dragging the arrow shaft, bindings remain with "keep" strategy packages/element/src/binding.ts288-291
• Point validation: validateElbowPoints() checks for valid routing packages/excalidraw/data/restore.ts631-650
• Self-binding repair: Special handling for arrows with both ends bound to the same element packages/excalidraw/data/restore.ts652-693
• Fixed segments: Can store fixedSegments for routing constraints packages/excalidraw/data/restore.ts390-396

Sources: packages/element/src/binding.ts281-291 packages/excalidraw/data/restore.ts628-693

---

Binding Restoration and Repair

Restoration Flow

Sources: packages/excalidraw/data/restore.ts527-694

Repair Operations

The restoration system applies these repairs:

Container Element Repair (repairContainerElement):

• Remove duplicate entries in boundElements array packages/excalidraw/data/restore.ts436-443
• Remove references to deleted bound elements packages/excalidraw/data/restore.ts446-448
• Set containerId on text elements that are missing it packages/excalidraw/data/restore.ts452-460

Bound Element Repair (repairBoundElement):

• Sync text element angle with container (except arrows: always 0) packages/excalidraw/data/restore.ts483-485
• Clear containerId if container doesn't exist packages/excalidraw/data/restore.ts487-490
• Add text to container's boundElements if missing packages/excalidraw/data/restore.ts496-506

Linear Element Repair:

• Remove startBinding/endBinding if target element doesn't exist packages/excalidraw/data/restore.ts611-625
• Only repair arrow elements (not lines without arrowheads)

Sources: packages/excalidraw/data/restore.ts420-625

Legacy Binding Migration

During restoration, legacy binding formats are migrated:

• boundElementIds → boundElements: Old format stored only IDs, new format includes type packages/excalidraw/data/restore.ts214-216
• Focus defaults: Missing focus property defaults to 0 packages/excalidraw/data/restore.ts134
• Elbow arrow binding conversion: Non-fixed bindings converted to FixedPointBinding packages/excalidraw/data/restore.ts136-147
• Fixed point normalization: normalizeFixedPoint() ensures valid coordinates packages/excalidraw/data/restore.ts143

Sources: packages/excalidraw/data/restore.ts124-156 packages/excalidraw/data/restore.ts214-216

---

Integration with Other Systems

Binding in Actions

Several action handlers interact with the binding system:

Action	Binding Interaction	Implementation
actionFlipHorizontal/Vertical	Rebinds arrows after flip transformation	packages/excalidraw/actions/actionFlip.ts161-167
actionBindText	Creates text-to-container binding	packages/excalidraw/actions/actionBoundText.tsx108-180
actionUnbindText	Removes text-to-container binding	packages/excalidraw/actions/actionBoundText.tsx53-105
changeProperty	Updates bound elements after style changes	packages/excalidraw/actions/actionProperties.tsx274-281

Sources: packages/excalidraw/actions/actionFlip.ts86-207 packages/excalidraw/actions/actionBoundText.tsx1-221

Binding Constants

Constant	Value	Purpose
FIXED_BINDING_DISTANCE	5	Pixel threshold for binding detection packages/element/src/binding.ts107
BINDING_HIGHLIGHT_THICKNESS	10	Visual highlight thickness for bind preview packages/element/src/binding.ts108
BOUND_TEXT_PADDING	20	Minimum padding for text inside containers packages/common/src/constants.ts

Sources: packages/element/src/binding.ts107-108 packages/excalidraw/actions/actionBoundText.tsx2-8