gridstack.js

gridstack.js is a mobile-friendly TypeScript library for building drag-and-drop, multi-column responsive dashboard layouts without any external runtime dependencies. A single call to GridStack.init() turns a container with grid-stack-item children into a fully interactive grid: items can be dragged, resized, nested (grid-in-grid), and serialized to/from plain JSON via save()/load(). Layout math (collision detection, compaction, column changes) lives in a headless GridStackEngine that has no DOM dependency, while a separate drag/drop subsystem handles native mouse and touch events directly, so the library needs neither jQuery nor jQuery UI.

The project ships official Angular, React, and Vue component wrappers in the same npm package alongside the vanilla core, so teams standardize on one grid engine across multiple frontend stacks instead of maintaining separate drag-and-drop implementations per framework. It has been actively maintained since 2014, with a long, explicit per-major-version migration guide in the README (v0.6 through v13) and a large community of production users building dashboards, admin panels, and page builders.

What You Get

• A dependency-free TypeScript core (no jQuery or jQuery UI required since v1/v6)
• Official Angular, React, and Vue component wrappers published in the same npm package
• CSS for responsive 1-to-12+ column grids, using CSS custom properties for column counts
• Native mouse and touch drag/resize handling built directly on browser events
• JSON save()/load() serialization, including nested sub-grid layouts
• An extensible GridStackEngine you can subclass to customize collision and move behavior

Common Use Cases

• Customizable analytics and BI dashboards where end users rearrange and resize widgets
• Admin panels and internal tools that need a movable, resizable layout
• No-code/low-code page and dashboard builders
• Nested, workspace-style UIs built from grid-in-grid panels

Under The Hood

Architecture The published GridStack class is a large DOM-facing facade that delegates all pure layout math to a separate, headless GridStackEngine, which owns node positions, column count, and max-row limits and performs collision detection, compaction, and column-resize recalculation without ever touching the DOM. A distinct family of drag/drop modules (draggable, resizable, droppable, touch handling) implements interaction purely via native mouse and touch events and is wired into the main class through a dedicated adapter, keeping DOM-event handling decoupled from grid math. Nested grids are supported by letting any grid item optionally own its own child GridStack instance, and a batch-update/on-change callback pattern in the engine defers DOM notification until a group of moves completes. Because every framework wrapper sits on top of the same core engine rather than reimplementing layout logic, a change to the engine’s collision or compaction algorithm affects correctness across the vanilla, Angular, React, and Vue surfaces uniformly.

Tech Stack The core is written in TypeScript with no runtime dependencies, built through a combination of a task runner for CSS/SCSS compilation and minification, a bundler for the distributable JS, and the TypeScript compiler for type declarations; the published package ships combined UMD-style bundles alongside ESM type definitions. Styling is hand-written SCSS compiled to CSS using CSS custom properties to drive column counts, replacing an older, class-generation-based approach to responsive columns. The Angular, React, and Vue wrappers each live in their own subdirectory with an independent build, and are published together under the same npm package. Testing runs on a modern unit-test runner with DOM emulation plus a browser-automation tool for end-to-end and regression coverage, and API documentation is generated automatically from the TypeScript source.

Code Quality The test suite is extensive, with dedicated spec files covering the layout engine, the main grid class, utilities, each drag/drop module, and a standing regression suite for previously fixed issues, plus separate end-to-end and integration test directories. Linting and full type-checking are wired into the test script so both run before tests execute. Internal-only fields follow a consistent underscore-prefixed naming convention, and the public type definitions are extensive and thorough, though a handful of fields rely on definite-assignment assertions that require careful constructor ordering. Error handling favors defensive logging and early returns over thrown exceptions, appropriate for a DOM library where a bad selector shouldn’t crash a host app. Continuous integration runs on an older CI provider rather than the repo’s GitHub Actions workflows, which are limited to documentation deployment.

API Design The public surface centers on a single static entry point that returns a full-featured instance and stores it back onto the DOM element it was initialized on, so consumers can retrieve their grid without holding an external reference. A JSON-first design lets an entire dashboard, including nested sub-grids, be described and restored as plain data, which pairs naturally with server-persisted layouts and is a step beyond what most comparable grid libraries offer. An explicit, documented extension point lets advanced users subclass the layout engine to customize move and collision behavior without forking the project, and the same core ships pre-built Angular, React, and Vue components so teams get one mental model across stacks rather than separate drag-and-drop libraries per framework. Public methods are thoroughly annotated with inline documentation and usage examples, and a long, carefully maintained per-major-version migration guide accompanies the changelog.