Box class

Axis-aligned bounding box for 2D spatial calculations

The Box class represents an axis-aligned bounding box with position (x, y) and dimensions (w, h). It provides methods for box manipulation, collision detection, and spatial queries.

Constructor

const box = new Box(x, y, w, h)

x · number · default: "0"

The x-coordinate of the box’s top-left corner

y · number · default: "0"

The y-coordinate of the box’s top-left corner

w · number · default: "0"

The width of the box

h · number · default: "0"

The height of the box

Properties

x · number

The x-coordinate of the box

y · number

The y-coordinate of the box

w · number

The width of the box

h · number

The height of the box

point · Vec

The top-left point of the box (getter/setter)

center · Vec

The center point of the box (getter/setter)

corners · Vec[]

Array of the four corner points [top-left, top-right, bottom-right, bottom-left]

sides · Array<[Vec, Vec]>

Array of the four sides as pairs of points

minX · number

The minimum x-coordinate (left edge)

maxX · number

The maximum x-coordinate (right edge)

minY · number

The minimum y-coordinate (top edge)

maxY · number

The maximum y-coordinate (bottom edge)

width · number

Alias for w (getter/setter)

height · number

Alias for h (getter/setter)

aspectRatio · number

The aspect ratio (width / height)

Instance methods

set

box.set(x: number, y: number, w: number, h: number): Box

Sets the box’s position and dimensions. Returns the box for chaining.

setTo

box.setTo(other: Box): Box

Copies another box’s values. Returns the box for chaining.

clone

box.clone(): Box

Creates a copy of the box.

expand

box.expand(other: Box): Box

Expands the box to include another box. Returns the box for chaining.

expandBy

box.expandBy(amount: number): Box

Expands the box by a given amount in all directions. Returns the box for chaining.

const box = new Box(0, 0, 100, 100)
box.expandBy(10) // Box is now (-10, -10, 120, 120)

translate

box.translate(delta: VecLike): Box

Moves the box by a delta vector. Returns the box for chaining.

const box = new Box(0, 0, 100, 100)
box.translate({ x: 10, y: 20 }) // Box is now (10, 20, 100, 100)

scale

box.scale(factor: number): Box

Scales the box by dividing position and dimensions by the factor. Returns the box for chaining.

collides

box.collides(other: Box): boolean

Checks if this box overlaps with another box.

const box1 = new Box(0, 0, 100, 100)
const box2 = new Box(50, 50, 100, 100)
const overlaps = box1.collides(box2) // true

contains

box.contains(other: Box): boolean

Checks if this box fully contains another box.

containsPoint

box.containsPoint(point: VecLike, margin?: number): boolean

Checks if a point is inside the box, with optional margin.

const box = new Box(0, 0, 100, 100)
const inside = box.containsPoint({ x: 50, y: 50 }) // true
const outsideWithMargin = box.containsPoint({ x: 105, y: 50 }, 10) // true

getHandlePoint

box.getHandlePoint(handle: SelectionCorner | SelectionEdge): Vec

Gets the position of a selection handle (corner or edge midpoint).

const box = new Box(0, 0, 100, 100)
const topLeft = box.getHandlePoint('top_left')
const rightEdge = box.getHandlePoint('right')

resize

box.resize(handle: SelectionCorner | SelectionEdge, dx: number, dy: number): void

Resizes the box by dragging a handle by dx/dy amounts.

snapToGrid

box.snapToGrid(size: number): void

Snaps the box’s position and dimensions to a grid.

toJson

box.toJson(): BoxModel

Converts the box to a plain object { x, y, w, h }.

equals

box.equals(other: Box | BoxModel): boolean

Checks if two boxes have identical values.

isValid

box.isValid(): boolean

Checks if all box values are finite numbers.

toFixed

box.toFixed(): Box

Rounds all values to two decimal places. Returns the box for chaining.

zeroFix

box.zeroFix(): Box

Ensures width and height are at least 1. Returns the box for chaining.

Static methods

Box.From

Box.From(box: BoxModel): Box

Creates a Box from a plain object.

const box = Box.From({ x: 0, y: 0, w: 100, h: 50 })

Box.FromCenter

Box.FromCenter(center: VecLike, size: VecLike): Box

Creates a box from a center point and size.

const box = Box.FromCenter({ x: 50, y: 50 }, { x: 100, y: 100 })
// Creates a box at (0, 0) with size (100, 100)

Box.FromPoints

Box.FromPoints(points: VecLike[]): Box

Creates a bounding box that contains all given points.

const points = [
  new Vec(10, 20),
  new Vec(100, 50),
  new Vec(50, 150)
]
const bounds = Box.FromPoints(points)

Box.Expand

Box.Expand(a: Box, b: Box): Box

Creates a new box that contains both input boxes.

Box.ExpandBy

Box.ExpandBy(box: Box, amount: number): Box

Creates a new box expanded by the given amount.

Box.Collides

Box.Collides(a: Box, b: Box): boolean

Checks if two boxes overlap.

Box.Contains

Box.Contains(a: Box, b: Box): boolean

Checks if box A fully contains box B.

Box.ContainsPoint

Box.ContainsPoint(box: Box, point: VecLike, margin?: number): boolean

Checks if a point is inside a box.

Box.Common

Box.Common(boxes: Box[]): Box

Creates a bounding box that contains all given boxes.

Box.Resize

Box.Resize(
  box: Box,
  handle: SelectionCorner | SelectionEdge,
  dx: number,
  dy: number,
  isAspectRatioLocked?: boolean
): { box: Box; scaleX: number; scaleY: number }

Creates a new resized box and returns the box along with scale factors.

const box = new Box(0, 0, 100, 100)
const result = Box.Resize(box, 'bottom_right', 50, 50, false)
console.log(result.box) // Resized box
console.log(result.scaleX, result.scaleY) // Scale factors

Box.Equals

Box.Equals(a: Box | BoxModel, b: Box | BoxModel): boolean

Checks if two boxes have identical values.

Box.ZeroFix

Box.ZeroFix(box: Box | BoxModel): Box

Creates a new box with width and height of at least 1.

Type definitions

BoxLike

type BoxLike = BoxModel | Box

SelectionEdge

type SelectionEdge = 'top' | 'right' | 'bottom' | 'left'

SelectionCorner

type SelectionCorner = 'top_left' | 'top_right' | 'bottom_right' | 'bottom_left'

SelectionHandle

type SelectionHandle = SelectionEdge | SelectionCorner

Example usage

import { Box, Vec } from 'tldraw'

// Create a box
const box = new Box(0, 0, 100, 50)

// Get properties
console.log(box.center) // Vec(50, 25)
console.log(box.aspectRatio) // 2
console.log(box.corners) // [Vec(0,0), Vec(100,0), Vec(100,50), Vec(0,50)]

// Manipulate
box.expandBy(10).translate({ x: 5, y: 5 })

// Collision detection
const other = new Box(50, 25, 100, 50)
if (box.collides(other)) {
  console.log('Boxes overlap!')
}

// Create from points
const points = [
  new Vec(10, 20),
  new Vec(100, 50),
  new Vec(50, 150)
]
const bounds = Box.FromPoints(points)