or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

coordinates.mdcss-utilities.mdevent-handling.mdexecution-context.mdfocus-management.mdhooks.mdindex.mdmath-operations.mdtype-guards.mdtypescript-utilities.md
tile.json

tessl/npm-dnd-kit--utilities

Internal utilities shared between @dnd-kit packages providing React hooks, coordinate manipulation, and DOM utilities.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@dnd-kit/utilities@3.2.x

To install, run

npx @tessl/cli install tessl/npm-dnd-kit--utilities@3.2.0

index.mddocs/

@dnd-kit/utilities

@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.

Package Information

  • Package Name: @dnd-kit/utilities
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @dnd-kit/utilities

Core Imports

import {
  // 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");

Basic Usage

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>
  );
}

Architecture

@dnd-kit/utilities is organized around several key areas:

  • React Hooks: Essential hooks for ref management, event handling, layout effects, and state management
  • Mathematical Operations: Functions for adding and subtracting numeric object properties
  • Coordinate System: Types and utilities for handling x,y coordinates in drag and drop operations
  • CSS Utilities: Transform and transition helpers for generating CSS strings
  • Event Handling: Type guards and utilities for working with DOM events
  • Execution Context: Cross-platform utilities for detecting DOM availability and window/document access
  • Focus Management: Utilities for finding focusable elements in the DOM
  • Type Guards: Functions for safely determining DOM element types
  • TypeScript Utilities: Generic type manipulation helpers

Capabilities

React Hooks

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;

React Hooks

Mathematical Operations

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;

Mathematical Operations

Coordinate System

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;

Coordinate System

CSS Utilities

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 };
};

CSS Utilities

Event Handling

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;

Event Handling

Execution Context

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;

Execution Context

Focus Management

Utilities for finding and managing focusable elements in the DOM.

function findFirstFocusableNode(element: HTMLElement): HTMLElement | null;

Focus Management

Type Guards

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;

Type Guards

TypeScript Utilities

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>>;

TypeScript Utilities