@dnd-kit/utilities is a TypeScript utility library providing internal utilities shared between @dnd-kit packages. It includes essential React hooks, coordinate manipulation utilities, CSS transformation helpers, event handling utilities, DOM manipulation functions, execution context utilities, focus management, type guards for DOM elements, and TypeScript utility types.
npm install @dnd-kit/utilitiesimport {
// React hooks
useCombinedRefs,
useEvent,
useIsomorphicLayoutEffect,
useInterval,
useLatestValue,
useLazyMemo,
useNodeRef,
usePrevious,
useUniqueId,
// Utility functions
add,
subtract,
getEventCoordinates,
CSS,
// Type definitions
type Coordinates,
type Transform,
type Transition
} from "@dnd-kit/utilities";
// React types (used by some hooks)
import { DependencyList, MutableRefObject } from "react";For CommonJS:
const {
useCombinedRefs,
useEvent,
add,
subtract,
CSS
} = require("@dnd-kit/utilities");import React, { useRef } from "react";
import {
useCombinedRefs,
useEvent,
CSS,
type Transform
} from "@dnd-kit/utilities";
function DraggableItem({ onDrag, children }) {
const nodeRef = useRef<HTMLDivElement>(null);
const customRef = useRef<HTMLDivElement>(null);
// Combine multiple refs into one
const combinedRef = useCombinedRefs(nodeRef, customRef);
// Create stable event handler
const handleDrag = useEvent(onDrag);
// Generate CSS transform
const transform: Transform = { x: 10, y: 20, scaleX: 1, scaleY: 1 };
const style = { transform: CSS.Transform.toString(transform) };
return (
<div ref={combinedRef} style={style} onDrag={handleDrag}>
{children}
</div>
);
}@dnd-kit/utilities is organized around several key areas:
Essential React hooks for building drag and drop interfaces, including ref management, event handling, and performance optimization.
function useCombinedRefs<T>(...refs: ((node: T) => void)[]): (node: T) => void;
function useEvent<T extends Function>(handler: T | undefined): (...args: any[]) => any;
const useIsomorphicLayoutEffect: typeof useLayoutEffect | typeof useEffect;
function useInterval(): readonly [(listener: Function, duration: number) => void, () => void];
function useLatestValue<T>(value: T, dependencies?: DependencyList): MutableRefObject<T>;
function useLazyMemo<T>(callback: (prevValue: T | undefined) => T, dependencies: any[]): T;
function useNodeRef(
onChange?: (newElement: HTMLElement | null, previousElement: HTMLElement | null) => void
): readonly [MutableRefObject<HTMLElement | null>, (element: HTMLElement | null) => void];
function usePrevious<T>(value: T): T | undefined;
function useUniqueId(prefix: string, value?: string): string;Utilities for adding and subtracting numeric values from object properties, useful for coordinate and dimension calculations.
function add<T extends Record<U, number>, U extends string>(
object: T,
...adjustments: Partial<T>[]
): T;
function subtract<T extends Record<U, number>, U extends string>(
object: T,
...adjustments: Partial<T>[]
): T;Types and utilities for handling x,y coordinates in drag and drop operations, including event coordinate extraction.
type Coordinates = {
x: number;
y: number;
};
function getEventCoordinates(event: Event): Coordinates | null;Transform and transition helpers for generating CSS strings from structured data, optimized for drag and drop animations.
type Transform = {
x: number;
y: number;
scaleX: number;
scaleY: number;
};
interface Transition {
property: string;
easing: string;
duration: number;
}
const CSS: {
Translate: { toString(transform: Transform | null): string | undefined };
Scale: { toString(transform: Transform | null): string | undefined };
Transform: { toString(transform: Transform | null): string | undefined };
Transition: { toString(transition: Transition): string };
};Type guards and utilities for working with DOM events, including touch and keyboard event detection.
function hasViewportRelativeCoordinates(
event: Event
): event is Event & Pick<PointerEvent, 'clientX' | 'clientY'>;
function isKeyboardEvent(event: Event | undefined | null): event is KeyboardEvent;
function isTouchEvent(event: Event | undefined | null): event is TouchEvent;Cross-platform utilities for detecting DOM availability and accessing window/document objects safely.
const canUseDOM: boolean;
function getOwnerDocument(target: Event['target']): Document;
function getWindow(target: Event['target']): typeof window;Utilities for finding and managing focusable elements in the DOM.
function findFirstFocusableNode(element: HTMLElement): HTMLElement | null;Type-safe functions for determining DOM element types, essential for cross-frame compatibility.
function isDocument(node: Node): node is Document;
function isHTMLElement(node: Node | Window): node is HTMLElement;
function isNode(node: Object): node is Node;
function isSVGElement(node: Node): node is SVGElement;
function isWindow(element: Object): element is typeof window;Generic type manipulation helpers for advanced TypeScript patterns.
type Arguments<T> = T extends (...args: infer U) => any ? U : never;
type DeepRequired<T> = { [K in keyof T]-?: Required<T[K]>; };
type FirstArgument<T> = T extends (firstArg: infer U, ...args: Array<any>) => any ? U : never;
type Without<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;