sidebar: auto

Guide

Quickstart

Install the package vue-draggable-grid via your favourite package manager. Include the library in your project:

import plugin from 'vue-draggable-grid';

Vue.use(plugin);

// Now create your app as usual

Inside the component where you want to use the grid define your grid and data as follows:

<template>
  <drag-grid v-model="items" :cols="4" :rows="4">
    <template #item="item">
      {{ item.data.text }}
    </template>
  </drag-grid>
</template>

<script>
export default {
  name: "YourComponent",
  data() {
    return {
      items: [
        {x: 1, y: 3, w: 2, h: 2, key: "item1", data: {text: "Hello world 1"},},
        {x: 2, y: 2, w: 2, h: 1, key: "item2", data: {text: "Hello world 2"},},
        {x: 3, y: 1, w: 1, h: 1, key: "item3", data: {text: "Hello world 3"},},
      ]
    }
  },
}
</script>

Blocking fields

A field (or cell) can be blocked via the disabledFields prop. The prop receives an array of objects, containing the coordinates of the blocked fields.

An example for a disabled fields property:

disabledFields: [
    {x: 1, y: 1},
    {x: 2, y: 3},
]

Prevent items from being dragged

To disable dragging of a specific item, simply set the attribute disabled of the item to true.

someDisabledItems: [
    { key: "key1", x: 1, y: 3, w: 1, h: 1, data: {} },
    { key: "key2", x: 2, y: 2, w: 1, h: 1, data: {} },
    { key: "key3", x: 3, y: 1, w: 1, h: 1, data: {}, disabled: true },
    { key: "key4", x: 1, y: 2, w: 1, h: 1, data: {}, disabled: true },
]

The highlighted items are not draggable.

Disabling the grid

If the boolean property disabled is set for the whole grid, the grid itself is disabled, and items can't be moved.

Programmatic validation of movements

It is also possible to supply a function to dynamically or programmatically hinder fields from being moved to, and items from being moved. This can be done by supplying a function which takes the x and y coordinates of the field as well as the key of the item. If false is returned, the movement is prohibited. The highlight which appears when dragging an element is also disabled for this field.

Examples for such methods are the following:

function blockField(x, y, key) {
    // We won't move items with ID 'obj8' and nothing into (3, 3) and (4, 3)
    if (x === 3 && y === 3) return false;
    if (x === 4 && y === 3) return false;
    return key !== "obj8";
};

function blockAllMoving() {
    return false;
};

Changing the highlight

The highlight is the grey-bordered rectangle which appears when dragging over a field.

Custom highlight

To customize the highlight, use the highlight slot inside the grid component.

<drag-grid
        v-model="items"
        :cols="3"
        :rows="2"
>
    <template #highlight>
        <div ref="highlight" class="custom-highlight">
            This is a custom highlight with a custom style!
        </div>
    </template>
</drag-grid>

Disabled highlight

To disable the highlight, use the no-highlight prop.

Changing items on move

It is possible to make changes to an item once it moved successfully. One can supply a function in the validate-element prop which gets called on a moved item and can make (in place) changes to it. Such a function could look like this:

function randomKey(element) {
    if (element.key.length !== 1) return;
    element.key += Math.random().toString(36).replace("0.", "");
};

This method changes the key of a moved item to a random string if the key has a length of 1. This is used inside example 2 (the tic-tac-toe game).

Multiple grids

To connect multiple grids they need to have the same context. If you supply the same string to the context prop of two grids, the items can be moved interchangeably.

::: warning Items are not deleted from the source grid if moved to a different one. You have to build a mechanism for this yourself. :::