BaseBoxShapeUtil • tldraw Docs

Table of contents

migrations
props
type
editor
options
Properties
Methods

Extends ShapeUtil<Shape>.

abstract class BaseBoxShapeUtil<
  Shape extends TLBaseBoxShape,
> extends ShapeUtil<Shape> {}

Constructor

from ShapeUtil

Constructs a new instance of the ShapeUtil class

Parameters

Name	Description
`editor`	`Editor`

Properties

migrations

staticoptional

from ShapeUtil

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

staticoptional

from ShapeUtil

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

Validation. Shapes will be validated using these props to stop bad data from being saved.
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 {
  DefaultColorStyle,
  ShapeUtil,
  T,
  TLBaseShape,
  TLDefaultColorStyle,
} 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,
  }
}

type

static

from ShapeUtil

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

static type: string

editor

from ShapeUtil

editor: Editor

options

from ShapeUtil

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( )

static

from ShapeUtil

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

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

Returns

canBeLaidOut( )

from ShapeUtil

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

canBeLaidOut(_shape: Shape, _info: TLShapeUtilCanBeLaidOutOpts): boolean

Parameters

Name	Description
`_shape`	`Shape`
`_info`	`TLShapeUtilCanBeLaidOutOpts`

Returns

boolean

canBind( )

from ShapeUtil

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

canBind(_opts: TLShapeUtilCanBindOpts): boolean

Parameters

Name	Description
`_opts`	`TLShapeUtilCanBindOpts`

Returns

boolean

canCrop( )

from ShapeUtil

Whether the shape can be cropped.

canCrop(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canCull( )

from ShapeUtil

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

Name	Description
`_shape`	`Shape`

Returns

boolean

canEdit( )

from ShapeUtil

Whether the shape can be double clicked to edit.

canEdit(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canEditInReadonly( )

from ShapeUtil

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

canEditInReadonly(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canReceiveNewChildrenOfType( )

from ShapeUtil

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

canReceiveNewChildrenOfType(_shape: Shape, _type: TLShape['type']): boolean

Parameters

Name	Description
`_shape`	`Shape`
`_type`	`TLShape['type']`

Returns

boolean

canResize( )

from ShapeUtil

Whether the shape can be resized.

canResize(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canResizeChildren( )

from ShapeUtil

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

canResizeChildren(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canScroll( )

from ShapeUtil

Whether the shape can be scrolled while editing.

canScroll(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canSnap( )

from ShapeUtil

Whether the shape can be snapped to by another shape.

canSnap(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

canTabTo( )

from ShapeUtil

Whether the shape can be tabbed to.

canTabTo(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

component( )

from ShapeUtil

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

abstract component(shape: Shape): any

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

any

getAriaDescriptor( )

from ShapeUtil

getAriaDescriptor(_shape: Shape): string | undefined

Parameters

Name	Description
`_shape`	`Shape`

Returns

string | undefined

getBoundsSnapGeometry( )

from ShapeUtil

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

getBoundsSnapGeometry(_shape: Shape): BoundsSnapGeometry

Parameters

Name	Description
`_shape`	`Shape`

Returns

BoundsSnapGeometry

getCanvasSvgDefs( )

from ShapeUtil

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[]

getClipPath( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape to get the clip path for

Returns

undefined | Vec[]

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

getDefaultProps( )

from ShapeUtil

Get the default props for a shape.

abstract getDefaultProps(): Shape['props']

getFontFaces( )

from ShapeUtil

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

getFontFaces(shape: Shape): TLFontFace[]

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLFontFace[]

getGeometry( )

getGeometry(shape: Shape): Geometry2d

Parameters

Name	Description
`shape`	`Shape`

Returns

Geometry2d

getHandles( )

optional

from ShapeUtil

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

getHandles?(shape: Shape): TLHandle[]

Example

util.getHandles?.(myShape)

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLHandle[]

getHandleSnapGeometry( )

getHandleSnapGeometry(shape: Shape): HandleSnapGeometry

Parameters

Name	Description
`shape`	`Shape`

Returns

HandleSnapGeometry

getInterpolatedProps( )

getInterpolatedProps(
  startShape: Shape,
  endShape: Shape,
  t: number
): Shape['props']

Parameters

Name	Description
`startShape`	`Shape`
`endShape`	`Shape`
`t`	`number`

Returns

Shape['props']

getText( )

from ShapeUtil

getText(_shape: Shape): string | undefined

Parameters

Name	Description
`_shape`	`Shape`

Returns

string | undefined

hideInMinimap( )

optional

from ShapeUtil

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

Name	Description
`_shape`	`Shape`

Returns

boolean

boolean indicating if this shape should hide in the minimap

hideResizeHandles( )

from ShapeUtil

Whether the shape should hide its resize handles when selected.

hideResizeHandles(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

hideRotateHandle( )

from ShapeUtil

Whether the shape should hide its rotation handles when selected.

hideRotateHandle(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

hideSelectionBoundsBg( )

from ShapeUtil

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

hideSelectionBoundsBg(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

hideSelectionBoundsFg( )

from ShapeUtil

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

hideSelectionBoundsFg(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

indicator( )

from ShapeUtil

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

abstract indicator(shape: Shape): any

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

any

isAspectRatioLocked( )

from ShapeUtil

Whether the shape's aspect ratio is locked.

isAspectRatioLocked(_shape: Shape): boolean

Parameters

Name	Description
`_shape`	`Shape`

Returns

boolean

isExportBoundsContainer( )

from ShapeUtil

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

Name	Description
`_shape`	`Shape` The shape to check

Returns

boolean

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

onBeforeCreate( )

optional

from ShapeUtil

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

Name	Description
`next`	`Shape` The next shape.

Returns

Shape | void

The next shape or void.

onBeforeUpdate( )

optional

from ShapeUtil

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

Name	Description
`prev`	`Shape` The previous shape.
`next`	`Shape` The next shape.

Returns

Shape | void

The next shape or void.

onChildrenChange( )

optional

from ShapeUtil

A callback called when a shape's children change.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial[] | void

An array of shape updates, or void.

onClick( )

optional

from ShapeUtil

A callback called when a shape is clicked.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onCrop( )

optional

from ShapeUtil

A callback called when a shape changes from a crop.

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

Parameters

Name	Description
`shape`	`Shape` The shape at the start of the crop.
`info`	`TLCropInfo<Shape>` Info about the crop.

Returns

Omit<TLShapePartial<Shape>, 'id' | 'type'> | undefined | void

A change to apply to the shape, or void.

onDoubleClick( )

optional

from ShapeUtil

A callback called when a shape is double clicked.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onDoubleClickCorner( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`info`	`TLClickEventInfo` Info about the corner.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onDoubleClickEdge( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`info`	`TLClickEventInfo` Info about the edge.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onDoubleClickHandle( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`handle`	`TLHandle` The handle that is double-clicked.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onDragShapesIn( )

optional

from ShapeUtil

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

Name	Description
`shape`	`Shape` The shape.
`shapes`	`TLShape[]` The shapes that are being dragged in.
`info`	`TLDragShapesInInfo`

Returns

void

onDragShapesOut( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`shapes`	`TLShape[]` The shapes that are being dragged out.
`info`	`TLDragShapesOutInfo`

Returns

void

onDragShapesOver( )

optional

from ShapeUtil

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

Name	Description
`shape`	`Shape` The shape.
`shapes`	`TLShape[]` The shapes that are being dragged over this one.
`info`	`TLDragShapesOverInfo`

Returns

void

onDropShapesOver( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`shapes`	`TLShape[]` The shapes that are being dropped over this one.
`info`	`TLDropShapesOverInfo`

Returns

void

onEditEnd( )

optional

from ShapeUtil

A callback called when a shape finishes being edited.

onEditEnd?(shape: Shape): void

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

void

onEditStart( )

optional

from ShapeUtil

A callback called when a shape starts being edited.

onEditStart?(shape: Shape): void

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

void

onHandleDrag( )

optional

from ShapeUtil

A callback called when a shape's handle changes.

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

Parameters

Name	Description
`shape`	`Shape` The current shape.
`info`	`TLHandleDragInfo<Shape>` An object containing the handle and whether the handle is 'precise' or not.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onHandleDragCancel( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`current`	`Shape` The current shape.
`info`	`TLHandleDragInfo<Shape>` An object containing the handle and whether the handle is 'precise' or not.

Returns

void

onHandleDragEnd( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`current`	`Shape` The current shape.
`info`	`TLHandleDragInfo<Shape>` An object containing the handle and whether the handle is 'precise' or not.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onHandleDragStart( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`info`	`TLHandleDragInfo<Shape>` An object containing the handle and whether the handle is 'precise' or not.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onResize( )

onResize(shape: any, info: TLResizeInfo<any>): any

Parameters

Name	Description
`shape`	`any`
`info`	`TLResizeInfo<any>`

Returns

any

onResizeCancel( )

optional

from ShapeUtil

A callback called when a shape resize is cancelled.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the resize.
`current`	`Shape` The current shape.

Returns

void

onResizeEnd( )

optional

from ShapeUtil

A callback called when a shape finishes resizing.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the resize.
`current`	`Shape` The current shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onResizeStart( )

optional

from ShapeUtil

A callback called when a shape starts being resized.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onRotate( )

optional

from ShapeUtil

A callback called when a shape changes from a rotation.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the rotation.
`current`	`Shape` The current shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onRotateCancel( )

optional

from ShapeUtil

A callback called when a shape rotation is cancelled.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the rotation.
`current`	`Shape` The current shape.

Returns

void

onRotateEnd( )

optional

from ShapeUtil

A callback called when a shape finishes rotating.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the rotation.
`current`	`Shape` The current shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onRotateStart( )

optional

from ShapeUtil

A callback called when a shape starts being rotated.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onTranslate( )

optional

from ShapeUtil

A callback called when a shape changes from a translation.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the translation.
`current`	`Shape` The current shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onTranslateCancel( )

optional

from ShapeUtil

A callback called when a shape translation is cancelled.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the translation.
`current`	`Shape` The current shape.

Returns

void

onTranslateEnd( )

optional

from ShapeUtil

A callback called when a shape finishes translating.

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

Parameters

Name	Description
`initial`	`Shape` The shape at the start of the translation.
`current`	`Shape` The current shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

onTranslateStart( )

optional

from ShapeUtil

A callback called when a shape starts being translated.

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

Parameters

Name	Description
`shape`	`Shape` The shape.

Returns

TLShapePartial<Shape> | void

A change to apply to the shape, or void.

shouldClipChild( )

optional

from ShapeUtil

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

Name	Description
`child`	`TLShape` The child shape to check

Returns

boolean

boolean indicating if this child should be clipped

toBackgroundSvg( )

optional

from ShapeUtil

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

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`ctx`	`SvgExportContext` ctx - The export context for the SVG - used for adding e.g. <def>s

Returns

null | Promise<null | ReactElement> | ReactElement

An SVG element.

toSvg( )

optional

from ShapeUtil

Get the shape as an SVG object.

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

Parameters

Name	Description
`shape`	`Shape` The shape.
`ctx`	`SvgExportContext` The export context for the SVG - used for adding e.g. <def>s

Returns

null | Promise<null | ReactElement> | ReactElement

An SVG element.