gridstack.js

Mobile-friendly modern Typescript library for dashboard layout and creation. Making a drag-and-drop, multi-column responsive dashboard has never been easier. Has multiple bindings and works great with Angular (included), React, Vue, Knockout.js, Ember and others (see frameworks section).

Inspired by no-longer maintained gridster, built with love.

Check http://gridstackjs.com and these demos.

If you find this lib useful, please donate PayPal (use “send to a friend” to avoid 3% fee) or Venmo (adumesny) and help support it!

Join us on Slack: https://gridstackjs.slack.com

Table of Contents generated with DocToc

• Demo and API Documentation
• Usage
• Install
• Include
• Basic usage
• Requirements
• Specific frameworks
• Extend Library
• Extend Engine
• Change grid columns
• Custom columns CSS (OLD, not needed with v12+)
• Override resizable/draggable options
• Touch devices support
• Migrating
• Migrating to v0.6
• Migrating to v1
• Migrating to v2
• Migrating to v3
• Migrating to v4
• Migrating to v5
• Migrating to v6
• Migrating to v7
• Migrating to v8
• Migrating to v9
• Migrating to v10
• Migrating to v11
• Migrating to v12
• jQuery Application
• Changes
• Usage Trend
• The Team

Demo and API Documentation

Please visit http://gridstackjs.com and these demos, and complete API documentation (markdown)

Usage

Install

yarn add gridstack
// or
npm install --save gridstack

Include

ES6 or Typescript

import 'gridstack/dist/gridstack.min.css';
import { GridStack } from 'gridstack';

Alternatively (single combined file, notice the -all.js) in html

<link href="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/gridstack.min.css" rel="stylesheet"/>
<script src="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/gridstack-all.js"></script>

Note: IE support was dropped in v2, but restored in v4.4 by an external contributor (I have no interest in testing+supporting obsolete browser so this likely will break again in the future) and DROPPED again in v12 (css variable needed). You can use the es5 files and polyfill (larger) for older browser instead. For example:

<link href="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/gridstack.min.css" rel="stylesheet"/>
<script src="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/es5/gridstack-poly.js"></script>
<script src="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/es5/gridstack-all.js"></script>

Basic usage

creating items dynamically...

// ...in your HTML






// ...in your script
var grid = GridStack.init();
grid.addWidget({w: 2, content: 'item 1'});

... or creating from list

// using serialize data instead of .addWidget()
const serializedData = [
  {x: 0, y: 0, w: 2, h: 2},
  {x: 2, y: 3, w: 3, content: 'item 2'},
  {x: 1, y: 3}
];

grid.load(serializedData);

... or DOM created items

// ...in your HTML








Item 1










Item 2 wider









// ...in your script
GridStack.init();

...or see list of all API and options available.

see stackblitz sample as running example too.

Requirements

GridStack no longer requires external dependencies as of v1 (lodash was removed in v0.5 and jquery API in v1). v3 is a complete HTML5 re-write removing need for jquery. v6 is native mouse and touch event for mobile support, and no longer have jquery-ui version. All you need to include now is gridstack-all.js and gridstack.min.css (layouts are done using CSS column based %).

Specific frameworks

search for 'gridstack' under NPM for latest, more to come...

• Angular: we ship out of the box an Angular wrapper - see Angular Component.
• Angular9: lb-gridstack Note: very old v0.3 gridstack instance so recommend for concept ONLY if you wish to use directive instead. Code has not been vented at as I use components.
• AngularJS: gridstack-angular
• Ember: ember-gridstack
• knockout: see demo using component, but check custom bindings ticket which is likely better approach.
• Rails: gridstack-js-rails
• React: work in progress to have wrapper code: see React Component. But also see demo with src, or react-gridstack-example, or read on what hooks to use
• Vue: see demo with v3 src or v2 src
• Aurelia: aurelia-gridstack, see demo

Extend Library

You can easily extend or patch gridstack with code like this:

// extend gridstack with our own custom method
GridStack.prototype.printCount = function() {
  console.log('grid has ' + this.engine.nodes.length + ' items');
};

let grid = GridStack.init();

// you can now call
grid.printCount();

Extend Engine

You can now (5.1+) easily create your own layout engine to further customize your usage. Here is a typescript example

import { GridStack, GridStackEngine, GridStackNode, GridStackMoveOpts } from 'gridstack';

class CustomEngine extends GridStackEngine {

  /** refined this to move the node to the given new location */
  public override moveNode(node: GridStackNode, o: GridStackMoveOpts): boolean {
    // keep the same original X and Width and let base do it all...
    o.x = node.x;
    o.w = node.w;
    return super.moveNode(node, o);
  }
}

GridStack.registerEngine(CustomEngine); // globally set our custom class

Change grid columns

GridStack makes it very easy if you need [1-12] columns out of the box (default is 12), but you always need 2 things if you need to customize this:

1) Change the column grid option when creating a grid to your number N

GridStack.init( {column: N} );

NOTE: step 2 is OLD and not needed with v12+ which uses CSS variables instead of classes

2) also include gridstack-extra.css if N < 12 (else custom CSS - see next). Without these, things will not render/work correctly.

<link href="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/gridstack.min.css" rel="stylesheet"/>
<link href="https://github.com/gridstack/gridstack.js/raw/v12.6.0/node_modules/gridstack/dist/gridstack-extra.min.css" rel="stylesheet"/>



...

Note: class .grid-stack-N will automatically be added and we include gridstack-extra.min.css which defines CSS for grids with custom [2-11] columns. Anything more and you'll need to generate the SASS/CSS yourself (see next).

See example: 2 grids demo with 6 columns

Custom columns CSS (OLD, not needed with v12+)

NOTE: step is OLD and not needed with v12+ which uses CSS variables instead of classes

If you need > 12 columns or want to generate the CSS manually you will need to generate CSS rules for .grid-stack-item[gs-w="X"] and .grid-stack-item[gs-x="X"].

For instance for 4-column grid you need CSS to be:

.gs-4 > .grid-stack-item[gs-x="1"]  { left: 25% }
.gs-4 > .grid-stack-item[gs-x="2"]  { left: 50% }
.gs-4 > .grid-stack-item[gs-x="3"]  { left: 75% }

.gs-4 > .grid-stack-item { width: 25% }
.gs-4 > .grid-stack-item[gs-w="2"]  { width: 50% }
.gs-4 > .grid-stack-item[gs-w="3"]  { width: 75% }
.gs-4 > .grid-stack-item[gs-w="4"]  { width: 100% }

Better yet, here is a SCSS code snippet, you can use sites like sassmeister.com to generate the CSS for you instead:

$columns: 20;
@function fixed($float) {
  @return round($float * 1000) / 1000; // total 2+3 digits being %
}
.gs-#{$columns} > .grid-stack-item {

  width: fixed(100% / $columns);

  @for $i from 1 through $columns - 1 {
    &[gs-x='#{$i}'] { left: fixed((100% / $columns) * $i); }
    &[gs-w='#{$i+1}'] { width: fixed((100% / $columns) * ($i+1)); }
  }
}

you can also use the SCSS src/gridstack-extra.scss included in NPM package and modify to add more columns.

Sample gulp command for 30 columns:

gulp.src('node_modules/gridstack/dist/src/gridstack-extra.scss')
        .pipe(replace('$start: 2 !default;','$start: 30;'))
        .pipe(replace('$end: 11 !default;','$end: 30;'))
        .pipe(sass({outputStyle: 'compressed'}))
        .pipe(rename({extname: '.min.css'}))
        .pipe(gulp.dest('dist/css'))

Override resizable/draggable options

You can override default resizable/draggable options. For instance to enable other then bottom right resizing handle you can init gridstack like:

GridStack.init({
  resizable: {
    handles: 'e,se,s,sw,w'
  }
});

Touch devices support

gridstack v6+ now support mobile out of the box, with the addition of native touch event (along with mouse event) for drag&drop and resize. Older versions (3.2+) required the jq version with added touch punch, but doesn't work well with nested grids.

This option is now the default:

let options = {
  alwaysShowResizeHandle: 'mobile' // true if we're on mobile devices
};
GridStack.init(options);

See example.

Migrating

Migrating to v0.6

starting in 0.6.x change event are no longer sent (for pretty much most nodes!) when an item is just added/deleted unless it also changes other nodes (was incorrect and causing inefficiencies). You may need to track added|removed events if you didn't and relied on the old broken behavior.

Migrating to v1

v1.0.0 removed Jquery from the API and external dependencies, which will require some code changes. Here is a list of the changes:

1. see previous step if not on v0.6 already

2. your code only needs to import GridStack from 'gridstack' or include gridstack.all.js and gristack.css (don't include other JS) and is recommended you do that as internal dependencies will change over time. If you are jquery based, see jquery app section.

3. code change:

OLD initializing code + adding a widget + adding an event:

// initialization returned Jquery element, requiring second call to get GridStack var
var grid = $('.grid-stack').gridstack(opts?).data('gridstack');

// returned Jquery element
grid.addWidget($('



 test 



'), undefined, undefined, 2, undefined, true);

// jquery event handler
$('.grid-stack').on('added', function(e, items) {/* items contains info */});

// grid access after init
var grid = $('.grid-stack').data('gridstack');

NEW ```js // element identifier defaults to '.grid-stack', returns the grid // Note: for Ty