# grid-layout-plus: Vue 3 grid layout, and the v2 rewrite

> grid-layout-plus is a draggable and resizable grid layout for Vue 3, migrated from Vue Grid Layout and rebuilt with script setup and normalised TypeScript. A 2.0 beta is out with breaking changes, replacing the implicit layout state with a controlled model, adding headless composables and exposing a DOM-free core for use outside a browser.

**qmhc/grid-layout-plus** — A draggable and resizable grid layout, for Vue 3.

- Repository: https://github.com/qmhc/grid-layout-plus
- Website: https://grid-layout-plus.netlify.app/
- Stars: 621 · Forks: 80
- Language: TypeScript
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/qmhc-grid-layout-plus

## Inherited from Vue Grid Layout, rewritten for Vue 3

The lineage explains most of the design. grid-layout-plus was originally migrated from Vue Grid Layout, which is a grid layout system for Vue 2 in the same family as Gridster and heavily inspired by React Grid Layout. The migration kept the familiar model of draggable and resizable widgets, and the rewrite moved it to the current Vue 3 idioms, being constructed with script setup and normalised TypeScript.

The feature list is the part worth reading closely, because each entry corresponds to a real layout problem. Widgets can be dragged and resized, and there is a static option for panels that should not move. Dragging and resizing are bounds checked, so a widget cannot be pushed outside its container. Widgets can be added or removed without rebuilding the grid, which matters for panels whose visibility is data driven. The layout can be serialised and restored, so a user arrangement can be persisted and reloaded. And there is automatic RTL support, so a grid in a right to left language does not need a separate implementation.

The homepage is a live documentation site, and the repository carries the docs, a dev-server playground, tests and a patches directory, so the project is maintained as a real library rather than a single component file.

## What v2 changes: controlled model, headless composables, no DOM

Version 2 is a rewrite rather than an increment, and the project is direct about the breaking changes. Four things are new. The layout becomes a controlled model, which means the state lives in your code rather than inside the component. Stylesheet imports become explicit, so the styles are no longer injected implicitly. There are headless composables, which expose the behaviour without the interface. And there is a DOM-free Core API, which is the most interesting of the four, because it means the layout logic can run where there is no document at all.

That last point changes what the library can be used for. A layout engine that needs a browser DOM can only be tested in a browser and only run in a browser, and any application that wants the same behaviour in a server render or a test environment has to mock the DOM. With a core that does not need one, the arrangement logic becomes a plain module. The package layout reflects the split, with the main entry point carrying the Vue component and a separate core entry point alongside it:
```json
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./es/index.mjs",
      "require": "./lib/index.cjs"
    },
```
The package is published as an ES module with a CommonJS build beside it, and TypeScript types are shipped in a dist directory.

## Choosing between the beta and the stable line

The install command differs depending on which line you want, which is the first thing to get right:
```sh
pnpm add grid-layout-plus@beta
```
The stable release is a separate tag, and the project says to stay on the 1.x line to keep the current release:
```sh
pnpm add grid-layout-plus@^1
```
The published versions show how the two lines have moved. The beta is at 2.0.0-beta.0, published on 2026-08-04, and the stable line is at v1.1.1 from October 2025, after v1.1.0 in May 2025. The last push to the repository was on 2026-10-20, so the beta is still being worked on.

The project also points anyone upgrading at an existing v1 project to a migration guide before touching anything, and provides a separate Chinese version of that guide. Given that a controlled layout model changes who owns the state, a document that walks through the conversion is worth reading before the upgrade rather than after the first bug report.

## Layout state is yours to keep

The features interact in a way that is worth understanding as a whole rather than as a list. A layout can be serialised and restored, which is what makes a user arrangement survive a reload, and the v2 controlled model is the natural partner to that, because the serialised layout becomes a plain value you hold in your own state and pass in. In v1, where the component owned the state, persistence meant reaching into the component to ask what the arrangement was, and that coupling is what the rewrite removes.

Widgets can also be added or removed without rebuilding the grid, so a panel list that changes with the data does not force a remount, and static widgets let you pin a control that should not be draggable. Bounds checking applies to both dragging and resizing, which is the behaviour that stops a saved layout from producing an overlapping mess when the viewport shrinks. The combination of automatic RTL support and a responsive layout means the same saved arrangement has to survive a direction change as well as a width change, and that is where serialisation earns its keep.

## How the project builds and tests itself

The package manifest shows a modern and fairly complete toolchain. The package is an ES module, managed with pnpm at a pinned version, and published with changesets, which is how a monorepo style release flow is usually run, with a separate version-packages script and a release script that builds before publishing. The build itself is a TypeScript script run through tsx, and the documentation site is a separate package built by its own command.

The testing has three layers. Unit tests run with vitest, with a coverage variant and a watch mode. End to end tests run with Playwright, which is the right tool for a component whose whole job is dragging and resizing, since those interactions are exactly what a unit test would mock away. And there is a type test target that runs the TypeScript compiler over a dedicated tsconfig in the tests directory, plus a release marker test that checks something about the release artefacts, which is the kind of check that catches a packaging mistake before publishing. Linting is layered too, with eslint for the code, stylelint for the styles, and prettier for formatting, and husky runs the staged checks before a commit. There is even a benchmark script that runs with the garbage collector exposed, which suggests the maintainer cares about what the layout engine costs.

## The gaps a user should plan around

Two things stand out. The first is the beta. A 2.0 that breaks the API of 1.x means every consumer who opts in is doing early adoption work, and the project itself flags the beta with an important notice at the top of the project notes. The second is that the library is a layout system, not an application shell: it does not decide where your layout is stored, how panels are titled, how a user saves their arrangement to your backend, or how permissions affect what can be moved. That is not a criticism so much as a boundary, and the v2 controlled model makes the boundary clearer rather than hiding it.

The project also carries files that describe how work happens in it, an AGENTS.md, a CLAUDE.md and a release process document, alongside a code of conduct and a changelog, and it uses changesets so that the changelog is generated from commit messages rather than written by hand. The licence is MIT, and the documentation is the only guide, which means the online site is the reference rather than a file in the repository.

## Conclusion

grid-layout-plus fits a Vue 3 dashboard or admin screen where users need to rearrange panels and the layout has to survive a reload, because serialization, bounds checking and adding or removing widgets without rebuilding the grid are all handled, and the v2 core without a DOM is a genuine option for tests and non-browser rendering. It is the wrong choice for a project that needs a stable release today, since the 2.0 line is still a beta with breaking changes, and the project publishes no 2.0 final. Before you upgrade, read the migration guide rather than the changelog alone, because the v2 changes are structural, and decide deliberately which version you pin, since the beta is installed under a different tag from the stable line. If you take the beta, keep an eye on the subpath exports, because the DOM-free core is exposed separately from the Vue entry point and that split is how you can use the layout logic without mounting a component.

## FAQ

### What is Grid Layout Plus?

It is a draggable and resizable grid layout system for Vue 3, originally migrated from Vue Grid Layout and rebuilt with script setup and normalised TypeScript. It supports draggable, resizable and static widgets, bounds checking, adding or removing widgets without rebuilding the grid, serialising and restoring a layout, automatic RTL support and responsive behaviour.

### How do I install the v2 beta of grid-layout-plus?

Run pnpm add grid-layout-plus@beta for the beta line, which is published as 2.0.0-beta.0. To stay on the stable release, run pnpm add grid-layout-plus@^1, which is currently v1.1.1.

### What changed in version 2?

Version 2 introduces a controlled Layout model, explicit stylesheet imports, headless composables and a DOM-free Core API, and it includes breaking changes from version 1. The project publishes a migration guide, with a separate Chinese version, for existing projects.

### Can a grid-layout-plus arrangement be saved and reloaded?

Yes, the layout can be serialised and restored, which in the v2 controlled model means the arrangement is a value your own code holds and passes in. The project also ships a separate core export that runs without a DOM.

### How is grid-layout-plus tested?

Unit tests run with vitest, end to end tests run with Playwright, and there is a type test target that runs the TypeScript compiler over the tests directory, plus a release marker test for the published artefacts. Linting uses eslint and stylelint with prettier for formatting, and husky runs the checks before a commit.

## Sources

- [License: MIT](https://github.com/qmhc/grid-layout-plus/blob/main/LICENSE)
- [Project website](https://grid-layout-plus.netlify.app/)
- [qmhc/grid-layout-plus on GitHub](https://github.com/qmhc/grid-layout-plus)
- [README](https://github.com/qmhc/grid-layout-plus/blob/main/README.md)
- [Releases](https://github.com/qmhc/grid-layout-plus/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qmhc-grid-layout-plus