React-Draggable

React-Draggable wraps an existing element and adds drag event handlers and CSS-transform-based positioning, without inserting any wrapper DOM node. Because it moves elements with CSS transforms rather than absolute-position offsets, dragging works regardless of the element’s original positioning scheme (relative, absolute, or static), and elements can be repositioned between drags without visual glitches.

The package ships two components: <Draggable>, a batteries-included component that manages its own position state, class names, and styling; and <DraggableCore>, a headless variant that exposes the same drag callbacks without applying any transforms or managing state, intended for libraries like react-resizable and react-grid-layout that need full control over positioning.

What You Get

• A <Draggable> component that wraps a child element and makes it draggable via CSS transforms, with no extra DOM nodes inserted
• A headless <DraggableCore> component exposing drag start/move/stop callbacks without managing position state or styles
• Configurable drag axis, bounds, grid-snapping, and a custom drag handle or cancel selector
• Controlled and uncontrolled positioning modes, with onDrag/onStart/onStop callbacks carrying delta and absolute coordinates
• Content Security Policy support via a nonce prop or opt-out of the injected user-select style
• Bundled TypeScript type definitions

Common Use Cases

• Draggable modals, panels, or floating widgets in dashboard and admin UIs
• Building custom drag-and-drop or free-form layout tools on top of <DraggableCore>
• Powering higher-level grid layout libraries such as react-grid-layout and react-resizable
• Draggable annotation handles or markers in canvas/SVG-based editors
• Kanban-style or whiteboard-style interfaces where elements need free positioning within bounds

Under The Hood

Architecture - <Draggable> (lib/Draggable.tsx) is a stateful wrapper around <DraggableCore> (lib/DraggableCore.tsx), the low-level component that attaches pointer/mouse/touch event listeners directly to the child DOM node (obtained via the required nodeRef) and computes position deltas on every move event. <Draggable> layers position state, CSS class name toggling (react-draggable, -dragging, -dragged), and CSS-transform application on top of the callbacks <DraggableCore> provides, while <DraggableCore> itself renders no additional markup and applies no transforms, leaving positioning entirely to the caller — this split is what lets react-grid-layout and react-resizable reuse the drag mechanics with their own layout logic.

Tech Stack - The library is authored in TypeScript (lib/*.tsx) and built with tsup into CJS, ESM, and a minified UMD/web bundle (build/web/react-draggable.min.js) referenced by the unpkg field for CDN usage. It has no runtime dependencies beyond React itself (peer dependency), keeping the installed footprint minimal. Tests run under Vitest, including a browser-mode configuration (vitest.browser.config.js) for real DOM/pointer-event behavior alongside the standard jsdom suite.

Code Quality - The test/ directory covers both components’ props and callback behavior, with yarn test:all running the standard suite plus a real-browser pass, indicating explicit attention to drag interactions that are hard to fully verify in jsdom alone. ESLint (flat config) and TypeScript’s tsc --noEmit typecheck are wired into make lint, and the maintainers track a versioned React-compatibility table (2.x through 4.x) in the README, showing deliberate handling of breaking changes across React major versions.

API Design - The API favors minimal ceremony: wrapping a single <div> in <Draggable> is enough to make it draggable, and the required nodeRef prop (replacing the deprecated findDOMNode pattern) is the main piece of boilerplate needed for React Strict Mode compatibility. Prop naming is consistent between the two components (axis, bounds, handle, cancel, onDrag/onStart/onStop), and the README documents a Content Security Policy escape hatch (nonce prop or enableUserSelectHack={false}) that many comparable libraries omit entirely.