ShapeUtil

abstract class ShapeUtil<Shape extends TLShape = TLShape> {}

Constructs a new instance of the ShapeUtil class

Parameters

Editor;

Properties

Migrations allow you to make changes to a shape's props over time. Read the shape prop migrations guide for more information.

static migrations?: LegacyMigrations | MigrationSequence | TLPropsMigrations;

Props allow you to define the shape's properties in a way that the editor can understand. This has two main uses:

1. Validation. Shapes will be validated using these props to stop bad data from being saved. 2. Styles. Each StyleProp in the props can be set on many shapes at once, and will be remembered from one shape to the next.

static props?: RecordProps<TLUnknownShape>;

Example

import {
  T,
  TLBaseShape,
  TLDefaultColorStyle,
  DefaultColorStyle,
  ShapeUtil,
} from "tldraw";

type MyShape = TLBaseShape<
  "mine",
  {
    color: TLDefaultColorStyle;
    text: string;
  }
>;

class MyShapeUtil extends ShapeUtil<MyShape> {
  static props = {
    // we use tldraw's built-in color style:
    color: DefaultColorStyle,
    // validate that the text prop is a string:
    text: T.string,
  };
}

The type of the shape util, which should match the shape's type.

static type: string;

editor: Editor;

Options for this shape util. If you're implementing a custom shape util, you can override this to provide customization options for your shape. If using an existing shape util, you can customizing this by calling ShapeUtil.configure.

options: {};

Methods

Configure this shape utils options.

static configure<T extends TLShapeUtilConstructor<any, any>>(
  this: T,
  options: T extends new (...args: any[]) => {
    options: infer Options;
  }
    ? Partial<Options>
    : never,
): T;

Parameters

T;

T extends new (...args: any[]) => {
  options: infer Options;
}
  ? Partial<Options>
  : never;

Returns

T;

Whether the shape can participate in layout functions such as alignment or distribution.

canBeLaidOut(shape: Shape, info: TLShapeUtilCanBeLaidOutOpts): boolean;

Parameters

Shape;

TLShapeUtilCanBeLaidOutOpts;

Returns

boolean;

Whether the shape can be bound to. See TLShapeUtilCanBindOpts for details.

canBind(_opts: TLShapeUtilCanBindOpts): boolean;

Parameters

TLShapeUtilCanBindOpts;

Returns

boolean;

Whether the shape can be cropped.

canCrop(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether this shape can be culled. By default, shapes are culled for performance reasons when they are outside of the viewport. Culled shapes are still rendered to the DOM, but have their display property set to none.

canCull(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape can be double clicked to edit.

canEdit(shape: Shape, info: TLEditStartInfo): boolean;

Parameters

Shape;

TLEditStartInfo;

Returns

boolean;

Whether the shape can be edited in read-only mode.

canEditInReadonly(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape can be edited while locked or while an ancestor is locked.

canEditWhileLocked(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Get whether the shape can receive children of a given type.

canReceiveNewChildrenOfType(shape: Shape, _type: TLShape["type"]): boolean;

Parameters

Shape;

TLShape["type"];

Returns

boolean;

Whether the shape can be resized.

canResize(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

When the shape is resized, whether the shape's children should also be resized.

canResizeChildren(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape can be scrolled while editing.

canScroll(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape can be snapped to by another shape.

canSnap(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape can be tabbed to.

canTabTo(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Get a JSX element for the shape (as an HTML element).

abstract component(shape: Shape): any;

Parameters

Shape;

Returns

any;

getAriaDescriptor(shape: Shape): string | undefined;

Parameters

Shape;

Returns

string | undefined;

Get the geometry to use when snapping to this this shape in translate/resize operations. See BoundsSnapGeometry for details.

getBoundsSnapGeometry(shape: Shape): BoundsSnapGeometry;

Parameters

Shape;

Returns

BoundsSnapGeometry;

Return elements to be added to the <defs> section of the canvases SVG context. This can be used to define SVG content (e.g. patterns & masks) that can be referred to by ID from svg elements returned by component.

Each def should have a unique key. If multiple defs from different shapes all have the same key, only one will be used.

getCanvasSvgDefs(): TLShapeUtilCanvasSvgDef[];

Get the clip path to apply to this shape's children.

The returned points should define the inner clip boundary - the area where children will be visible. If your shape has a stroke, you should inset the clip path by half the stroke width so children are clipped to the inner edge of the stroke rather than its center line.

getClipPath?(shape: Shape): undefined | Vec[];

Example

override getClipPath(shape: MyShape): Vec[] | undefined {
  const strokeWidth = 2
  const inset = strokeWidth / 2
  // Return points inset by half the stroke width
  return [
    new Vec(inset, inset),
    new Vec(shape.props.w - inset, inset),
    new Vec(shape.props.w - inset, shape.props.h - inset),
    new Vec(inset, shape.props.h - inset),
  ]
}

Parameters

Shape;

Returns

undefined | Vec[];

Array of points defining the clipping polygon in local coordinates, or undefined if no clipping

Get the default props for a shape.

abstract getDefaultProps(): Shape["props"];

Get the font faces that should be rendered in the document in order for this shape to render correctly.

getFontFaces(shape: Shape): TLFontFace[];

Parameters

Shape;

Returns

TLFontFace[];

Get the shape's geometry.

abstract getGeometry(shape: Shape, opts?: TLGeometryOpts): Geometry2d;

Parameters

Shape;

TLGeometryOpts;

Returns

Geometry2d;

Get an array of handle models for the shape. This is an optional method.

getHandles?(shape: Shape): TLHandle[];

Example

util.getHandles?.(myShape);

Parameters

Shape;

Returns

TLHandle[];

Get the geometry to use when snapping handles to this shape. See HandleSnapGeometry for details.

getHandleSnapGeometry(shape: Shape): HandleSnapGeometry;

Parameters

Shape;

Returns

HandleSnapGeometry;

Get a Path2D for rendering the shape's indicator on the canvas.

When implemented, this is used instead of ShapeUtil.indicator for more efficient canvas-based indicator rendering. Shapes that return undefined will fall back to SVG-based rendering via ShapeUtil.indicator.

For complex indicators that need clipping (e.g., arrows with labels), return an object with path, clipPath, and additionalPaths properties.

getIndicatorPath(shape: Shape): TLIndicatorPath | undefined;

Parameters

Shape;

Returns

TLIndicatorPath | undefined;

A Path2D to stroke, or an object with clipping info, or undefined to use SVG fallback.

Get the interpolated props for an animating shape. This is an optional method.

getInterpolatedProps?(
  startShape: Shape,
  endShape: Shape,
  progress: number,
): Shape["props"];

Example

util.getInterpolatedProps?.(startShape, endShape, t);

Parameters

Shape;

Shape;

number;

Returns

Shape["props"];

Return user IDs referenced in shape-specific props. Used when copying shapes to include referenced users on the clipboard. Override this if your shape stores user IDs in custom props.

getReferencedUserIds(shape: Shape): string[];

Parameters

Shape;

Returns

string[];

getText(shape: Shape): string | undefined;

Parameters

Shape;

Returns

string | undefined;

Whether a specific shape should hide in the minimap.

If not defined, the default behavior is to show all shapes in the minimap.

hideInMinimap?(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

boolean indicating if this shape should hide in the minimap

Whether the shape should hide its resize handles when selected.

hideResizeHandles(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape should hide its rotation handles when selected.

hideRotateHandle(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape should hide its selection bounds background when selected.

hideSelectionBoundsBg(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Whether the shape should hide its selection bounds foreground when selected.

hideSelectionBoundsFg(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

Get JSX describing the shape's indicator (as an SVG element).

abstract indicator(shape: Shape): any;

Parameters

Shape;

Returns

any;

Whether the shape's aspect ratio is locked.

isAspectRatioLocked(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

By default, the bounds of an image export are the bounds of all the shapes it contains, plus some padding. If an export includes a shape where isExportBoundsContainer is true, then the padding is skipped if the bounds of that shape contains all the other shapes. This is useful in cases like annotating on top of an image, where you usually want to avoid extra padding around the image if you don't need it.

isExportBoundsContainer(shape: Shape): boolean;

Parameters

Shape;

Returns

boolean;

True if this shape should be treated as an export bounds container

A callback called just before a shape is created. This method provides a last chance to modify the created shape.

onBeforeCreate?(next: Shape): Shape | void;

Example

onBeforeCreate = (next) => {
  return { ...next, x: next.x + 1 };
};

Parameters

Shape;

Returns

Shape | void;

The next shape or void.

A callback called just before a shape is updated. This method provides a last chance to modify the updated shape.

onBeforeUpdate?(prev: Shape, next: Shape): Shape | void;

Example

onBeforeUpdate = (prev, next) => {
  if (prev.x === next.x) {
    return { ...next, x: next.x + 1 };
  }
};

Parameters

Shape;

Shape;

Returns

Shape | void;

The next shape or void.

A callback called when a shape's children change.

onChildrenChange?(shape: Shape): TLShapePartial[] | void;

Parameters

Shape;

Returns

TLShapePartial[] | void;

An array of shape updates, or void.

A callback called when a shape is clicked.

onClick?(shape: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape changes from a crop.

onCrop?(
  shape: Shape,
  info: TLCropInfo<Shape>,
): Omit<TLShapePartial<Shape>, "id" | "type"> | undefined | void;

Parameters

Shape;

TLCropInfo<Shape>;

Returns

Omit<TLShapePartial<Shape>, "id" | "type"> | undefined | void;

A change to apply to the shape, or void.

A callback called when a shape is double clicked.

onDoubleClick?(shape: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape's corner is double clicked.

onDoubleClickCorner?(
  shape: Shape,
  info: TLClickEventInfo,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLClickEventInfo;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape's edge is double clicked.

onDoubleClickEdge?(
  shape: Shape,
  info: TLClickEventInfo,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLClickEventInfo;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape's handle is double clicked.

onDoubleClickHandle?(
  shape: Shape,
  handle: TLHandle,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLHandle;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when some other shapes are dragged into this one. This fires when the shapes are dragged over the shape for the first time.

onDragShapesIn?(
  shape: Shape,
  shapes: TLShape[],
  info: TLDragShapesInInfo,
): void;

Parameters

Shape;

TLShape[];

TLDragShapesInInfo;

Returns

void;

A callback called when some other shapes are dragged out of this one.

onDragShapesOut?(
  shape: Shape,
  shapes: TLShape[],
  info: TLDragShapesOutInfo,
): void;

Parameters

Shape;

TLShape[];

TLDragShapesOutInfo;

Returns

void;

A callback called when some other shapes are dragged over this one. This fires when the shapes are dragged over the shape for the first time (after the onDragShapesIn callback), and again on every update while the shapes are being dragged.

onDragShapesOver?(
  shape: Shape,
  shapes: TLShape[],
  info: TLDragShapesOverInfo,
): void;

Example

onDragShapesOver = (shape, shapes) => {
  this.editor.reparentShapes(shapes, shape.id);
};

Parameters

Shape;

TLShape[];

TLDragShapesOverInfo;

Returns

void;

A callback called when some other shapes are dropped over this one.

onDropShapesOver?(
  shape: Shape,
  shapes: TLShape[],
  info: TLDropShapesOverInfo,
): void;

Parameters

Shape;

TLShape[];

TLDropShapesOverInfo;

Returns

void;

A callback called when a shape finishes being edited.

onEditEnd?(shape: Shape): void;

Parameters

Shape;

Returns

void;

A callback called when a shape starts being edited.

onEditStart?(shape: Shape): void;

Parameters

Shape;

Returns

void;

A callback called when a shape's handle changes.

onHandleDrag?(
  shape: Shape,
  info: TLHandleDragInfo<Shape>,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLHandleDragInfo<Shape>;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape's handle drag is cancelled.

onHandleDragCancel?(current: Shape, info: TLHandleDragInfo<Shape>): void;

Parameters

Shape;

TLHandleDragInfo<Shape>;

Returns

void;

A callback called when a shape's handle finishes being dragged.

onHandleDragEnd?(
  current: Shape,
  info: TLHandleDragInfo<Shape>,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLHandleDragInfo<Shape>;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape's handle starts being dragged.

onHandleDragStart?(
  shape: Shape,
  info: TLHandleDragInfo<Shape>,
): TLShapePartial<Shape> | void;

Parameters

Shape;

TLHandleDragInfo<Shape>;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape changes from a resize.

onResize?(
  shape: Shape,
  info: TLResizeInfo<Shape>,
): Omit<TLShapePartial<Shape>, "id" | "type"> | undefined | void;

Parameters

Shape;

TLResizeInfo<Shape>;

Returns

Omit<TLShapePartial<Shape>, "id" | "type"> | undefined | void;

A change to apply to the shape, or void.

A callback called when a shape resize is cancelled.

onResizeCancel?(initial: Shape, current: Shape): void;

Parameters

Shape;

Shape;

Returns

void;

A callback called when a shape finishes resizing.

onResizeEnd?(initial: Shape, current: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape starts being resized.

onResizeStart?(shape: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape changes from a rotation.

onRotate?(initial: Shape, current: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape rotation is cancelled.

onRotateCancel?(initial: Shape, current: Shape): void;

Parameters

Shape;

Shape;

Returns

void;

A callback called when a shape finishes rotating.

onRotateEnd?(initial: Shape, current: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape starts being rotated.

onRotateStart?(shape: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape changes from a translation.

onTranslate?(initial: Shape, current: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape translation is cancelled.

onTranslateCancel?(initial: Shape, current: Shape): void;

Parameters

Shape;

Shape;

Returns

void;

A callback called when a shape finishes translating.

onTranslateEnd?(initial: Shape, current: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

A callback called when a shape starts being translated.

onTranslateStart?(shape: Shape): TLShapePartial<Shape> | void;

Parameters

Shape;

Returns

TLShapePartial<Shape> | void;

A change to apply to the shape, or void.

Whether a specific child shape should be clipped by this shape. Only called if getClipPath returns a valid polygon.

If not defined, the default behavior is to clip all children.

shouldClipChild?(child: TLShape): boolean;

Parameters

TLShape;

Returns

boolean;

boolean indicating if this child should be clipped

Get the shape's background layer as an SVG object.

toBackgroundSvg?(
  shape: Shape,
  ctx: SvgExportContext,
): null | Promise<null | ReactElement> | ReactElement;

Parameters

Shape;

SvgExportContext;

Returns

null | Promise<null | ReactElement> | ReactElement;

An SVG element.

Get the shape as an SVG object.

toSvg?(
  shape: Shape,
  ctx: SvgExportContext,
): null | Promise<null | ReactElement> | ReactElement;

Parameters

Shape;

SvgExportContext;

Returns

null | Promise<null | ReactElement> | ReactElement;

An SVG element.

Whether to use the legacy React-based indicator rendering.

Override this to return false if your shape implements ShapeUtil.getIndicatorPath for canvas-based indicator rendering.

useLegacyIndicator(): boolean;