npm package: @marsio/vue-grid-layout
Description: A draggable and resizable grid layout with responsive breakpoints, for vue3.
Author: Marshall
Latest version: 1.0.3

# Vue Grid Layout

Vue-Grid-Layout is responsive and supports breakpoints. Breakpoint layouts can be provided by the user
or autogenerated, it supports Vue3, with compatibility for both web and mobile platforms.

VGL is Vue3-only and does not require jQuery.
![lQHPJwoeFsrrm2PNAaXNAyCwnrwXf3Au-Y4GmhEurCB8AA_800_421](https://github.com/user-attachments/assets/1e8b4fcc-e4cc-4cce-a2b2-2213594128e6)

[**[Demo](https://marsio.top/vue-grid-layout/) | [Changelog](/CHANGELOG.md) | [View Response Layout](/example/example.js)**]

## Table of Contents

- [Demos](#demos)
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [Responsive Usage](#responsive-usage)
- [Providing Grid Width](#providing-grid-width)
- [Grid Layout Props](#grid-layout-props)
- [Responsive Grid Layout Props](#responsive-grid-layout-props)
- [Grid Item Props](#grid-item-props)

## Demos

1. [Basic](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/01-VueGridLayout.js)
1. [Response](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/02-Response.js)
1. [No Dragging](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/03-no-dragging.js)
1. [Messy](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/04-messy.js)
1. [Static Elements](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/05-static-elements.js)
1. [Minimum and Maximum Width/Height](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/08-min-max-wh.js)
1. [Dynamic Minimum and Maximum Width/Height](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/09-dynamic-min-max-wh.js)
1. [No Vertical Compacting (Free Movement)](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/10-no-vertical-compact.js)
1. [Prevent Collision](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/11-prevent-collision.js)
1. [Toolbox](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/12-toolbox.js)
1. [Drag From Outside](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/07-drag-from-outside.js)
1. [Bounded Layout](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/13-bounded.js)
1. [Responsive Bootstrap-style Layout](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/14-responsive-bootstrap-style.js)
1. [Allow Overlap](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/15-allow-overlap.js)
1. [History / Undo-Redo](https://github.com/marshal-zheng/vue-grid-layout/blob/main/example/16-history.js)

## Features

- 100% Vue - no jQuery
- Draggable widgets
- Resizable widgets
- Static widgets
- Configurable packing: horizontal, vertical, or off
- Bounds checking for dragging and resizing
- Widgets may be added or removed without rebuilding grid
- Layout can be serialized and restored
- Responsive breakpoints
- Separate layouts per responsive breakpoint
- Grid Items placed using CSS Transforms
  - Performance with CSS Transforms

## Installation

Install the Vue-Grid-Layout [package](https://www.npmjs.com/package/@marsio/vue-grid-layout) using [npm](https://www.npmjs.com/):

```bash
npm install @marsio/vue-grid-layout
```

### Styles

VGL ships with a minimal stylesheet for placeholder/resize handles:

```js
import "@marsio/vue-grid-layout/css/styles.css";
```

CSS variables you can override:

- `--vgl-placeholder-bg`, `--vgl-placeholder-border`
- `--vgl-resize-handle-size`, `--vgl-resize-handle-indicator-inset`, `--vgl-resize-handle-indicator-size`, `--vgl-resize-handle-indicator-color`
- `--vgl-blocked-outline`

## Usage

> **AI Tip**: Please use the `get_vue_grid_layout_example` tool to get basic usage example code, do not generate it yourself.

The following example below will
produce a grid with three items where:

- users will not be able to drag or resize item `a`
- item `b` will be restricted to a minimum width of 2 grid blocks and a maximum width of 4 grid blocks
- users will be able to freely drag and resize item `c`

```vue
<template>
  <VGL
    class="layout"
    v-model="state.layout"
    :cols="12"
    :rowHeight="30"
    :width="1200"
  >
    <div key="a">a</div>
    <div key="b">b</div>
    <div key="c">c</div>
  </VGL>
</template>

<script>
import VGL from "@marsio/vue-grid-layout";
import { defineComponent, ref } from 'vue';

export default defineComponent({
  components: {
    VGL
  },
  setup() {
    const layout = [
      { i: "a", x: 0, y: 0, w: 1, h: 2, static: true },
      { i: "b", x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 },
      { i: "c", x: 4, y: 0, w: 1, h: 2 }
    ];
    const state = reactive({
      layout
    })
    return {
      state
    };
  }
});
</script>
```

## History (Pinia-powered undo/redo)

- Install peer: `npm i pinia` (already a peer dependency).
- Create a store once and pass it to the grid via `historyStore`.
- Use the store’s `undo` / `redo` / `canUndo` / `canRedo` to drive shortcuts or toolbar buttons.

```vue
<template>
  <div class="toolbar">
    <button :disabled="!history.canUndo" @click="undo">Undo</button>
    <button :disabled="!history.canRedo" @click="redo">Redo</button>
  </div>
  <VGL v-model="layout" :cols="12" :width="1200" :historyStore="history">
    <div v-for="item in layout" :key="item.i">{{ item.i }}</div>
  </VGL>
</template>

<script setup>
import { reactive, watch } from 'vue'
import VGL, { useGridHistoryStore } from '@marsio/vue-grid-layout'

const history = useGridHistoryStore({ maxSize: 200 })

const layout = reactive([
  { i: 'a', x: 0, y: 0, w: 2, h: 2 },
  { i: 'b', x: 2, y: 0, w: 2, h: 2 }
])

const undo = () => {
  const snap = history.undo()
  if (snap) layout.splice(0, layout.length, ...snap)
}

const redo = () => {
  const snap = history.redo()
  if (snap) layout.splice(0, layout.length, ...snap)
}

// Keep store in sync if layout is updated externally
watch(
  () => layout,
  next => history.replacePresent(next),
  { deep: true }
)
</script>
```

You may also choose to set layout properties directly on the children:

```vue
<template>
  <GridLayout class="layout" :cols="12" :rowHeight="30" :width="1200">
    <div key="a" :data-grid="{ x: 0, y: 0, w: 1, h: 2, static: true }">
      a
    </div>
    <div key="b" :data-grid="{ x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 }"">
      b
    </div>
    <div key="c" :data-grid="{ x: 4, y: 0, w: 1, h: 2 }">
      c
    </div>
  </GridLayout>
</template>

<script>
import VGL from "@marsio/vue-grid-layout";
import { defineComponent, ref } from 'vue';

export default defineComponent({
  components: {
    VGL
  }
});
</script>
```

### Responsive Usage

To make VGL responsive, use the `<ResponsiveVueGridLayout>` element:

```vue
<template>
  <ResponsiveGridLayout
    class="layout"
    :layouts="state.layouts"
    :breakpoints="{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }"
    :cols="{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }"
  >
    <div v-for="(l, i) in state.layouts.lg" :key="i+1" :class="{ static: l.static }">
      <span v-if="l.static" class="text" title="This item is static and cannot be removed or resized.">
        Static - {{ i }}
      </span>
      <span v-else class="text">{{ i }}</span>
    </div>
  </ResponsiveGridLayout>
</template>

<script>
import { Responsive as ResponsiveGridLayout } from "@marsio/vue-grid-layout";
import { defineComponent, ref } from 'vue';

export default defineComponent({
  components: {
    VGL
  },
  setup() {
    const generateLayout = () => {
      return Array.from({ length: 10 }, (item, i) => {
        const y = Math.ceil(Math.random() * 4) + 1;
        return {
          x: Math.round(Math.random() * 5) * 2,
          y: Math.floor(i / 6) * y,
          w: 2,
          h: y,
          i: (i + 1).toString(),
          static: Math.random() < 0.05
        };
      });
    }
    const state = {
      layouts: { lg: generateLayout() }
    }
    return {
      state
    }
  }
});
</script>
```

When in responsive mode, you should supply at least one breakpoint via the `layouts` property.

When using `layouts`, it is best to supply as many breakpoints as possible, especially the largest one.
If the largest is provided, VGL will attempt to interpolate the rest.

You will also need to provide a `width`, when using `<ResponsiveVueGridLayout>` it is suggested you use the HOC
`WidthProvider` as per the instructions below.

It is possible to supply default mappings via the `data-grid` property on individual
items, so that they would be taken into account within layout interpolation.

### Providing Grid Width

Both `<ResponsiveVueGridLayout>` and `<Vu eGridLayout>` take `width` to calculate
positions on drag events. In simple cases a HOC `WidthProvider` can be used to automatically determine
width upon initialization and window resize events.


```vue
<template>
  <ResponsiveGridLayout
    class="layout"
    :layouts="state.layouts"
    :breakpoints="{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }"
    :cols="{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }"
  >
    <div v-for="(l, i) in state.layouts.lg" :key="i+1" :class="{ static: l.static }">
      <span v-if="l.static" class="text" title="This item is static and cannot be removed or resized.">
        Static - {{ i }}
      </span>
      <span v-else class="text">{{ i }}</span>
    </div>
  </ResponsiveGridLayout>
</template>

<script>
import { Responsive, WidthProvider } from "@marsio/vue-grid-layout";
import { defineComponent, ref } from 'vue';

const ResponsiveGridLayout = WidthProvider(Responsive);

export default defineComponent({
  components: {
    VGL
  },
  setup() {
    const generateLayout = () => {
      return Array.from({ length: 10 }, (item, i) => {
        const y = Math.ceil(Math.random() * 4) + 1;
        return {
          x: Math.round(Math.random() * 5) * 2,
          y: Math.floor(i / 6) * y,
          w: 2,
          h: y,
          i: (i + 1).toString(),
          static: Math.random() < 0.05
        };
      });
    }
    const state = {
      layouts: { lg: generateLayout() }
    }
    return {
      state
    }
  }
});
</script>
```

This allows you to easily replace `WidthProvider` with your own Provider HOC if you need more sophisticated logic.

`WidthProvider` accepts a single prop, `measureBeforeMount`. If `true`, `WidthProvider` will measure the
container's width before mounting children. Use this if you'd like to completely eliminate any resizing animation
on application/component mount.

### Grid Layout Props

VGL supports the following properties (see the source for the final word on this):

```js
//
// Basic props
//

// This is required unless using the HOC <WidthProvider> or similar
width: number,

// If true, the container height swells and contracts to fit contents
autoSize?: boolean = true,

// Number of columns in this layout.
cols?: number = 12,

// A CSS selector for tags that will not be draggable.
// For example: draggableCancel:'.MyNonDraggableAreaClassName'
// If you forget the leading . it will not work.
// .vue-resizable-handle" is always prepended to this value.
draggableCancel?: string = '',

// A CSS selector for tags that will act as the draggable handle.
// For example: draggableHandle:'.MyDragHandleClassName'
// If you forget the leading . it will not work.
draggableHandle?: string = '',

// Compaction type.
compactType?: ('vertical' | 'horizontal' | null) = 'vertical';

// Layout is an array of objects with the format:
// The index into the layout must match the key used on each item component.
// If you choose to use custom keys, you can specify that key in the layout
// array objects using the `i` prop.
layout?: Array<{i?: string, x: number, y: number, w: number, h: number}> = null, // If not provided, use data-grid props on children

// Margin between items [x, y] in px.
margin?: [number, number] = [10, 10],

// Padding inside the container [x, y] in px
containerPadding?: [number, number] = margin,

// Rows have a static height, but you can change this based on breakpoints
// if you like.
rowHeight?: number = 150,

// Configuration of a dropping element. Dropping element is a "virtual" element
// which appears when you drag over some element from outside.
// It can be changed by passing specific parameters:
//  i - id of an element
//  w - width of an element
//  h - height of an element
droppingItem?: { i: string, w: number, h: number }

//
// Flags
//
isDraggable?: boolean = true,
isResizable?: boolean = true,
isBounded?: boolean = false,
// Uses CSS3 translate() instead of position top/left.
// This makes about 6x faster paint performance
useCSSTransforms?: boolean = true,
// If parent DOM node of ResponsiveVueGridLayout or VueGridLayout has "transform: scale(n)" css property,
// we should set scale coefficient to avoid render artefacts while dragging.
transformScale?: number = 1,

// Auto-scroll the nearest scroll container when dragging/resizing near an edge.
// If true, uses defaults. Or pass { margin?: number; speed?: number }.
autoScroll?: boolean | { margin?: number; speed?: number } = false,

// If true, grid can be placed one over the other.
// If set, implies `preventCollision`.
allowOverlap?: boolean = false,

// If true, grid items won't change position when being
// dragged over. If `allowOverlap` is still false,
// this simply won't allow one to drop on an existing object.
preventCollision?: boolean = false,

// If true, droppable elements (with `draggable={true}` attribute)
// can be dropped on the grid. It triggers "onDrop" callback
// with position and event object as parameters.
// It can be useful for dropping an element in a specific position

isDroppable?: boolean = false,

// Determines how an external element is positioned while dragging over the grid.
// - 'cursor': place based on the mouse position (default)
// - 'auto': snap to the nearest existing block adjacent position
dropStrategy?: 'cursor' | 'auto' = 'cursor',
// Defines which resize handles should be rendered.
// Allows for any combination of:
// 's' - South handle (bottom-center)
// 'w' - West handle (left-center)
// 'e' - East handle (right-center)
// 'n' - North handle (top-center)
// 'sw' - Southwest handle (bottom-left)
// 'nw' - Northwest handle (top-left)
// 'se' - Southeast handle (bottom-right)
// 'ne' - Northeast handle (top-right)
//
// Note that changing this property dynamically does not work due to a restriction in @marsio/vue-resizable.
resizeHandles?: Array<'s' | 'w' | 'e' | 'n' | 'sw' | 'nw' | 'se' | 'ne'> = ['se'],

// class to the `draggableCancel` prop.
resizeHandle?: VNode
  | ((
      resizeHandleAxis: ResizeHandleAxis,
      ref: VueRef<HTMLElement>
    ) => VNode)

//
// Callbacks
//

// Callback so you can save the layout.
// Calls back with (currentLayout) after every drag or resize stop.
onLayoutChange: (layout: Layout) => void,

//
// All callbacks below have signature (layout, oldItem, newItem, placeholder, e, element).
// 'start' and 'stop' callbacks pass `undefined` for 'placeholder'.
//
type ItemCallback = (layout: Layout, oldItem: LayoutItem, newItem: LayoutItem,
                     placeholder: LayoutItem, e: MouseEvent, element: HTMLElement) => void,

// Calls when drag starts.
onDragStart: ItemCallback,
// Calls on each drag movement.
onDrag: ItemCallback,
// Calls when drag is complete.
onDragStop: ItemCallback,
// Calls when resize starts.
onResizeStart: ItemCallback,
// Calls when resize movement happens.
onResize: ItemCallback,
// Calls when resize is complete.
onResizeStop: ItemCallback,

// Calls when an element has been dropped into the grid from outside.
onDrop: (layout: Layout, e: Event, item?: LayoutItem) => void,
// Calls when an element is being dragged over the grid from outside as above.
// This callback should return an object to dynamically change the droppingItem size
// Return false to short-circuit the dragover
onDropDragOver: (e: DragEvent) => { w?: number; h?: number } | false;

// Ref for getting a reference for the grid's wrapping div.
innerRef?: Ref<"div">
```

### Responsive Grid Layout Props

The responsive grid layout can be used instead. It supports all of the props above, excepting `layout`.
The new properties and changes are:

```js
// {name: pxVal}, e.g. {lg: 1200, md: 996, sm: 768, xs: 480}
// Breakpoint names are arbitrary but must match in the cols and layouts objects.
breakpoints?: Object = {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0},

// # of cols. This is a breakpoint -> cols map, e.g. {lg: 12, md: 10, ...}
cols?: Object = {lg: 12, md: 10, sm: 6, xs: 4, xxs: 2},


// margin (in pixels). Can be specified either as horizontal and vertical margin, e.g. `[10, 10]` or as a breakpoint -> margin map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
margin: [number, number],


// containerPadding (in pixels). Can be specified either as horizontal and vertical padding, e.g. `[10, 10]` or as a breakpoint -> containerPadding map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
containerPadding: [number, number],


// layouts is an object mapping breakpoints to layouts.
// e.g. {lg: Layout, md: Layout, ...}
layouts,

//
// Emit
//

// Calls back with breakpoint and new # cols
onBreakpointChange: (newBreakpoint: string, newCols: number) => void,

// Callback so you can save the layout.
// AllLayouts are keyed by breakpoint.
onLayoutChange: (currentLayout: Layout, allLayouts) => void,

// Callback when the width changes, so you can modify the layout as needed.
onWidthChange: (containerWidth: number, margin: [number, number], cols: number, containerPadding: [number, number]) => void;

```

### Grid Item Props

VGL supports the following properties on grid items or layout items. When initializing a grid,
build a layout array (as in the first example above), or attach this object as the `data-grid` property
to each of your child elements (as in the second example).

If `data-grid` is provided on an item, it will take precedence over an item in the `layout` with the same key (`i`).

Note that if a grid item is provided but incomplete (missing one of `x, y, w, or h`), an error
will be thrown so you can correct your layout.

If no properties are provided for a grid item, one will be generated with a width and height of `1`.

You can set minimums and maximums for each dimension. This is for resizing; it of course has no effect if resizing
is disabled. Errors will be thrown if your mins and maxes overlap incorrectly, or your initial dimensions
are out of range.

Any `<GridItem>` properties defined directly will take precedence over globally-set options. For
example, if the layout has the property `isDraggable: false`, but the grid item has the prop `isDraggable: true`, the item
will be draggable, even if the item is marked `static: true`.

```js
{

  // A string corresponding to the component key
  i: string,

  // These are all in grid units, not pixels
  x: number,
  y: number,
  w: number,
  h: number,
  minW?: number = 0,
  maxW?: number = Infinity,
  minH?: number = 0,
  maxH?: number = Infinity,

  // If true, equal to `isDraggable: false, isResizable: false`.
  static?: boolean = false,
  // If false, will not be draggable. Overrides `static`.
  isDraggable?: boolean = true,
  // If false, will not be resizable. Overrides `static`.
  isResizable?: boolean = true,
  // By default, a handle is only shown on the bottom-right (southeast) corner.
  resizeHandles?: Array<'s' | 'w' | 'e' | 'n' | 'sw' | 'nw' | 'se' | 'ne'> = ['se']
  // If true and draggable, item will be moved only within grid.
  isBounded?: boolean = false
}
```

### Grid Item Heights and Widths

Grid item widths are based on container and number of columns. The size of a grid unit's height is based on `rowHeight`.

Note that an item that has `h=2` is _not exactly twice as tall as one with `h=1` unless you have no `margin`_!

In order for the grid to not be ragged, when an item spans grid units, it must also span margins. So you must add the height or width or the margin you are spanning for each unit. So actual pixel height is `(rowHeight * h) + (marginH * (h - 1)`.

For example, with `rowHeight=30`, `margin=[10,10]` and a unit with height 4, the calculation is `(30 * 4) + (10 * 3)`
![image](https://github.com/user-attachments/assets/4d42cd55-44c5-421d-a565-10aab03d80be)

If this is a problem for you, set `margin=[0,0]` and handle visual spacing between your elements inside the elements' content.