Element Types and Creation

Relevant source files

• excalidraw-app/tests/collab.test.tsx
• packages/element/src/duplicate.ts
• packages/element/src/fractionalIndex.ts
• packages/element/src/mutateElement.ts
• packages/element/tests/duplicate.test.tsx
• packages/excalidraw/CHANGELOG.md
• packages/excalidraw/actions/actionBoundText.tsx
• packages/excalidraw/data/__snapshots__/transform.test.ts.snap
• packages/excalidraw/data/restore.ts
• packages/excalidraw/data/transform.test.ts
• packages/excalidraw/data/transform.ts
• packages/excalidraw/fonts/Fonts.ts
• packages/excalidraw/tests/__snapshots__/move.test.tsx.snap
• packages/excalidraw/tests/__snapshots__/multiPointCreate.test.tsx.snap
• packages/excalidraw/tests/test-utils.ts

This document describes the element type system in Excalidraw and the mechanisms for creating elements programmatically. It covers all available element types, the ExcalidrawElementSkeleton simplified input format, the convertToExcalidrawElements transformation function, and the newElement* constructor functions.

For information about element properties, transformations, and mutations after creation, see Element Properties and Transformations. For element binding mechanisms, see Element Binding System. For data restoration and migration of elements from stored formats, see Data Restoration and Migration.

Element Type Hierarchy

The following diagram shows the type hierarchy of all Excalidraw elements and their key properties:

Sources: packages/excalidraw/data/restore.ts244-418 packages/excalidraw/data/transform.ts176-211 packages/element/src/types.ts

Base Element Properties

All Excalidraw elements share a common set of base properties, regardless of their specific type:

Property	Type	Description
id	string	Unique identifier, generated by randomId()
type	string	Element type discriminator
x, y	number	Position coordinates
width, height	number	Dimensions
angle	Radians	Rotation angle
strokeColor	string	Stroke color
backgroundColor	string	Fill color
fillStyle	"solid" | "hachure" | "cross-hatch"	Fill pattern
strokeWidth	number	Stroke width
strokeStyle	"solid" | "dashed" | "dotted"	Stroke pattern
roughness	number	Roughness level for hand-drawn effect
opacity	number	Opacity (0-100)
groupIds	readonly GroupId[]	Group memberships
frameId	FrameId | null	Parent frame
roundness	StrokeRoundness | null	Corner/edge roundness
boundElements	readonly Binding[]	Bound elements (arrows, text)
version	number	Element version for collaboration
versionNonce	number	Random nonce for version
isDeleted	boolean	Soft deletion flag
seed	number	Random seed for roughness
index	FractionalIndex	Z-order fractional index
link	string | null	Hyperlink URL
locked	boolean	Locked from editing

Sources: packages/excalidraw/data/restore.ts177-220 packages/element/src/types.ts

Element Types

Generic Shape Elements

The three basic shape types—rectangle, ellipse, and diamond—share identical properties and are represented by the ExcalidrawGenericElement type:

Generic shapes are created using the newElement function. They can optionally contain bound text elements (see text binding below).

Sources: packages/excalidraw/data/transform.ts529-546 packages/excalidraw/data/restore.ts401-406

Linear Elements

Linear elements (line and arrow) contain an array of points defining their path:

Property	Type	Description
points	readonly LocalPoint[]	Array of [x, y] coordinate pairs
lastCommittedPoint	LocalPoint | null	Last point during creation
startBinding	PointBinding | null	Binding to element at start
endBinding	PointBinding | null	Binding to element at end
startArrowhead	Arrowhead | null	Start arrowhead type
endArrowhead	Arrowhead | null	End arrowhead type

Line elements additionally have:

• polygon: boolean - Whether to close the path as a polygon

Arrow elements are a specialized subtype:

• Default endArrowhead is "arrow"
• Can have elbowed: true for elbow arrows with orthogonal segments
• Elbow arrows use FixedPointBinding instead of PointBinding

Sources: packages/excalidraw/data/restore.ts316-398 packages/excalidraw/data/transform.ts548-576

Text Elements

Text elements render text content and can exist standalone or bound to containers:

Property	Type	Description
text	string	Text content
fontSize	number	Font size in pixels
fontFamily	FontFamilyValues	Font family ID
textAlign	"left" | "center" | "right"	Horizontal alignment
verticalAlign	"top" | "middle" | "bottom"	Vertical alignment
containerId	string | null	ID of container element
originalText	string	Original unwrapped text
autoResize	boolean	Whether to auto-resize
lineHeight	number	Line height multiplier

Text elements are created with newTextElement. The measureText function calculates dimensions based on font properties:

Sources: packages/excalidraw/data/restore.ts251-300 packages/excalidraw/data/transform.ts578-597

Image Elements

Image elements display embedded or linked images:

Property	Type	Description
fileId	FileId	Reference to file in BinaryFiles
status	"pending" | "saved" | "error"	Loading status
scale	[number, number]	Scale factors [x, y]
crop	ImageCrop | null	Crop settings

Images are created with newImageElement and require a fileId that references a file in the BinaryFiles storage.

Sources: packages/excalidraw/data/restore.ts309-315 packages/excalidraw/data/transform.ts599-606

Free-Draw Elements

Free-draw elements represent hand-drawn paths:

Property	Type	Description
points	readonly LocalPoint[]	Path points
pressures	readonly number[]	Pressure values (pen input)
simulatePressure	boolean	Whether to simulate pressure
lastCommittedPoint	LocalPoint | null	Last point during drawing

Sources: packages/excalidraw/data/restore.ts301-308

Frame Elements

Frames are container elements that group other elements:

Property	Type	Description
name	string | null	Frame name
children	readonly string[]	IDs of contained elements (skeleton only)

Two frame types exist:

• frame: Standard frame created with newFrameElement
• magicframe: AI-generated frame created with newMagicFrameElement

The children property only exists in the skeleton format and is used during conversion to set the frameId on child elements.

Sources: packages/excalidraw/data/restore.ts407-411 packages/excalidraw/data/transform.ts608-631

Embeddable Elements

Embeddable elements display external content:

Property	Type	Description
validated	boolean (legacy)	Validation status (moved to private state)

Two embeddable types:

• iframe: Generic iframe embed
• embeddable: Validated embeddable content

Sources: packages/excalidraw/data/restore.ts404-406 packages/excalidraw/CHANGELOG.md206

Element Creation Patterns

ExcalidrawElementSkeleton

The ExcalidrawElementSkeleton type provides a simplified, declarative format for creating elements without specifying all required properties. It allows partial specification of element properties:

Key differences from full elements:

• Only requires essential properties (type, position coordinates)
• Optional id (auto-generated if not provided)
• Optional label property to create bound text
• Optional start/end properties on linear elements to create bindings
• Frame children as array of IDs (converted to frameId on children)

Sources: packages/excalidraw/data/transform.ts176-211

convertToExcalidrawElements

The convertToExcalidrawElements function transforms an array of ExcalidrawElementSkeleton objects into fully-formed ExcalidrawElement objects:

Function signature:

Options:

• regenerateIds: If true (default), generates new IDs. Set to false to preserve IDs from skeleton.

Key behaviors:

1. Creates elements via type-specific constructors
2. Handles default dimensions (DEFAULT_DIMENSION = 100)
3. Creates bound text for label property
4. Creates bindings for linear elements with start/end
5. Converts frame children to child element frameId properties
6. Synchronizes fractional indices via syncInvalidIndices

Sources: packages/excalidraw/data/transform.ts508-685

Element Creation Flow

Sources: packages/excalidraw/data/transform.ts520-685 packages/excalidraw/actions/actionBoundText.tsx224-273

Constructor Functions

newElement (Generic Shapes)

Creates rectangle, ellipse, or diamond elements:

Sources: packages/excalidraw/data/transform.ts540-544 packages/excalidraw/actions/actionBoundText.tsx238-273

newLinearElement (Lines)

Creates line elements with points:

Sources: packages/excalidraw/data/transform.ts551-557

newArrowElement (Arrows)

Creates arrow elements:

Sources: packages/excalidraw/data/transform.ts563-576

newTextElement (Text)

Creates text elements:

Text dimensions are calculated automatically via measureText based on font properties.

Sources: packages/excalidraw/data/transform.ts578-597 packages/excalidraw/actions/actionBoundText.tsx224-232

newImageElement (Images)

Creates image elements:

Sources: packages/excalidraw/data/transform.ts599-606

newFrameElement & newMagicFrameElement (Frames)

Creates frame or magicframe elements:

Sources: packages/excalidraw/data/transform.ts608-631

Special Creation Features

Label Property (Bound Text)

Both container shapes and linear elements can have a label property in their skeleton that automatically creates bound text:

The label is converted to a text element bound to the container via:

1. bindTextToContainer for shapes
2. Similar logic for arrows (via boundElements)

Process:

1. Text element created with newTextElement
2. Text positioned via computeBoundTextPosition
3. Container resized via redrawTextBoundingBox
4. Bidirectional binding established:
   • Text: containerId set to container ID
   • Container: boundElements includes text binding

Sources: packages/excalidraw/data/transform.ts219-244 packages/excalidraw/actions/actionBoundText.tsx155-173

Arrow Bindings (start/end)

Linear elements can specify start and end properties in their skeleton to create bindings to other elements:

Binding creation:

1. If id specified: binds to existing element
2. If type specified without id: creates new element
3. Calls bindLinearElement to establish binding
4. Adjusts points by 0.5 pixels to avoid overlap with bound elements

Sources: packages/excalidraw/data/transform.ts246-480

Frame Children Assignment

Frames specify children as an array of element IDs in the skeleton. During conversion, these IDs are converted to frameId properties on the child elements:

The frame itself gets positioned and sized based on the bounding box of its children (calculated via getCommonBounds).

Sources: packages/excalidraw/data/transform.ts608-665

Default Values and Constants

Constant	Value	Usage
DEFAULT_DIMENSION	100	Default width/height for shapes
DEFAULT_LINEAR_ELEMENT_PROPS.width	100	Default width for lines/arrows
DEFAULT_LINEAR_ELEMENT_PROPS.height	0	Default height for lines/arrows
DEFAULT_FONT_FAMILY	Varies	Default font family
DEFAULT_FONT_SIZE	Varies	Default font size
DEFAULT_ELEMENT_PROPS	Object	Default stroke, fill, opacity, etc.

Sources: packages/excalidraw/data/transform.ts212-217 packages/excalidraw/data/restore.ts4-20

Element Restoration vs Creation

While this page focuses on creating new elements, the restoration process (handled by restoreElement and restoreElements) is used when:

• Loading saved scenes
• Importing data
• Handling collaboration updates
• Migrating from legacy formats

Key differences:

• Restoration preserves existing IDs, versions, and timestamps
• Handles legacy property migrations (e.g., strokeSharpness → roundness)
• Repairs broken bindings and container relationships
• Validates and syncs fractional indices

For details on restoration, see Data Restoration and Migration.

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