Geometry Utilities

API reference for geometry utilities and classes in dnd-kit

The geometry package provides utilities for working with points, rectangles, positions, and distances in 2D space.

Point

A class representing a location in a two-dimensional coordinate system.

class Point implements Coordinates {
  constructor(public x: number, public y: number)
}

Constructor

x · number · required

Coordinate of the point on the horizontal axis

y · number · required

Coordinate of the point on the vertical axis

Static Methods

Point.delta

Returns the delta (difference) between two points.

static delta(a: Point, b: Point): Point

a · Point · required

First point

b · Point · required

Second point

delta · Point

A new Point representing the difference (a.x - b.x, a.y - b.y)

Point.distance

Returns the distance (hypotenuse) between two points.

static distance(a: Point, b: Point): number

a · Point · required

First point

b · Point · required

Second point

distance · number

The Euclidean distance between the two points

Point.equals

Returns true if both points have the same coordinates.

static equals(a: Point, b: Point): boolean

a · Point · required

First point

b · Point · required

Second point

equals · boolean

True if both points are equal

Point.from

Creates a Point from coordinates.

static from(coordinates: Coordinates): Point

coordinates · Coordinates · required

An object with x and y properties

point · Point

A new Point instance

Usage Example

import {Point} from '@dnd-kit/geometry';

const point1 = new Point(10, 20);
const point2 = new Point(30, 40);

const delta = Point.delta(point1, point2);
// Point { x: -20, y: -20 }

const distance = Point.distance(point1, point2);
// 28.284271247461902

const areEqual = Point.equals(point1, point2);
// false

const point3 = Point.from({x: 5, y: 10});
// Point { x: 5, y: 10 }

---

Rectangle

A class representing a rectangular shape in 2D space.

class Rectangle implements Shape {
  constructor(
    public left: number,
    public top: number,
    public width: number,
    public height: number
  )
}

Constructor

left · number · required

The x-coordinate of the left edge

top · number · required

The y-coordinate of the top edge

width · number · required

The width of the rectangle

height · number · required

The height of the rectangle

Properties

center · Point

The center point of the rectangle

area · number

The area of the rectangle (width × height)

bottom · number

The y-coordinate of the bottom edge (top + height)

right · number

The x-coordinate of the right edge (left + width)

aspectRatio · number

The aspect ratio of the rectangle (width / height)

corners · Coordinates[]

An array of the four corner coordinates

boundingRectangle · BoundingRectangle

An object containing width, height, left, top, right, and bottom properties

scale · object

The scale factors for x and y axes (default: {x: 1, y: 1})

Methods

translate

Translates the rectangle by the given offsets.

translate(x: number, y: number): Rectangle

x · number · required

The x-axis offset

y · number · required

The y-axis offset

rectangle · Rectangle

A new Rectangle instance at the translated position

equals

Checks if this rectangle is equal to another shape.

equals(shape: Shape): boolean

shape · Shape · required

The shape to compare with

equals · boolean

True if the shapes are equal

containsPoint

Checks if a point is contained within the rectangle.

containsPoint(point: Point): boolean

point · Point · required

The point to check

contains · boolean

True if the point is inside the rectangle

intersectionArea

Calculates the intersection area with another shape.

intersectionArea(shape: Shape): number

shape · Shape · required

The shape to check intersection with

area · number

The area of intersection, or 0 if shapes don’t intersect

intersectionRatio

Calculates the intersection ratio with another shape.

intersectionRatio(shape: Shape): number

shape · Shape · required

The shape to check intersection with

ratio · number

The intersection ratio calculated as: intersectionArea / (shapeArea + thisArea - intersectionArea)

Static Methods

Rectangle.from

Creates a Rectangle from a BoundingRectangle.

static from(rect: BoundingRectangle): Rectangle

rect · BoundingRectangle · required

An object with top, left, width, and height properties

rectangle · Rectangle

A new Rectangle instance

Rectangle.delta

Calculates the delta between two rectangles based on alignment.

static delta(
  a: BoundingRectangle,
  b: BoundingRectangle,
  alignment?: Alignment
): Point

a · BoundingRectangle · required

First rectangle

b · BoundingRectangle · required

Second rectangle

alignment · Alignment · default: "{x: 'center', y: 'center'}"

The alignment point to use for comparison. Can be ‘start’, ‘center’, or ‘end’ for each axis.

delta · Point

The delta between the aligned points of the two rectangles

Rectangle.intersectionRatio

Calculates the intersection ratio between two rectangles.

static intersectionRatio(a: BoundingRectangle, b: BoundingRectangle): number

a · BoundingRectangle · required

First rectangle

b · BoundingRectangle · required

Second rectangle

ratio · number

The intersection ratio

Usage Example

import {Rectangle, Point} from '@dnd-kit/geometry';

const rect = new Rectangle(0, 0, 100, 50);

console.log(rect.center);
// Point { x: 50, y: 25 }

console.log(rect.area);
// 5000

console.log(rect.aspectRatio);
// 2

const translated = rect.translate(10, 20);
// Rectangle { left: 10, top: 20, width: 100, height: 50 }

const point = new Point(25, 25);
console.log(rect.containsPoint(point));
// true

const rect2 = new Rectangle(50, 25, 100, 50);
console.log(rect.intersectionArea(rect2));
// 1250

const delta = Rectangle.delta(
  rect.boundingRectangle,
  rect2.boundingRectangle,
  {x: 'start', y: 'start'}
);
// Point { x: 50, y: 25 }

---

Position

A class that tracks the current, previous, and initial positions with history and velocity tracking.

class Position extends ValueHistory<Point> {
  constructor(initialValue: Coordinates)
}

Constructor

initialValue · Coordinates · required

The initial coordinates

Properties

current · Point

The current position

previous · Point | undefined

The previous position, or undefined if not yet moved

initial · Point

The initial position

delta · Point

The delta between current and initial positions (computed)

direction · 'up' | 'down' | 'left' | 'right' | null

The direction of movement based on the delta between current and previous positions (computed)

velocity · Point

The velocity in pixels per 100ms for x and y axes

Methods

reset

Resets the position to initial or provided coordinates.

reset(coordinates?: Coordinates): void

coordinates · Coordinates

Optional coordinates to reset to (defaults to initial value)

Usage Example

import {Position} from '@dnd-kit/geometry';

const position = new Position({x: 0, y: 0});

position.current = {x: 10, y: 20};
console.log(position.delta);
// Point { x: 10, y: 20 }

position.current = {x: 20, y: 20};
console.log(position.direction);
// 'right'

console.log(position.velocity);
// { x: ..., y: 0 }

position.reset();
console.log(position.current);
// Point { x: 0, y: 0 }

---

exceedsDistance

Returns true if a set of relative coordinates exceeds a given distance.

function exceedsDistance(
  coordinates: Coordinates,
  distance: Distance
): boolean

Parameters

coordinates · Coordinates · required

The coordinates to check (typically a delta)

distance · Distance · required

The distance threshold. Can be:

• A number (Euclidean distance)
• An object with x and y properties (both axes must exceed)
• An object with only x (horizontal distance)
• An object with only y (vertical distance)

Returns

exceeds · boolean

True if the coordinates exceed the specified distance

Usage Example

import {exceedsDistance} from '@dnd-kit/geometry';

const delta = {x: 10, y: 5};

// Euclidean distance
console.log(exceedsDistance(delta, 8));
// true (distance is ~11.18)

// Both axes must exceed
console.log(exceedsDistance(delta, {x: 5, y: 5}));
// true (x: 10 > 5 && y: 5 >= 5)

// Only horizontal
console.log(exceedsDistance(delta, {x: 15}));
// false (10 < 15)

// Only vertical
console.log(exceedsDistance(delta, {y: 3}));
// true (5 > 3)

---

Types

Coordinates

type Coordinates = {
  x: number;
  y: number;
};

BoundingRectangle

type BoundingRectangle = {
  width: number;
  height: number;
  top: number;
  left: number;
  right: number;
  bottom: number;
};

Alignment

type Alignment = {
  x: 'start' | 'center' | 'end';
  y: 'start' | 'center' | 'end';
};

Distance

type Distance =
  | number
  | Coordinates
  | Pick<Coordinates, 'x'>
  | Pick<Coordinates, 'y'>;

Axis

enum Axis {
  Horizontal = 'x',
  Vertical = 'y',
}

enum Axes {
  Both = 'both',
  Horizontal = 'x',
  Vertical = 'y',
}