TypeScript/Javascript lib for dashboard layout and creation, no external dependencies, with many wrappers (React, Angular, Ember, knockout...)
npm install omega-gridstackgridstack.js
============
Mobile-friendly Javascript library (with Typescript bindings) for dashboard layout and creation. Making a drag-and-drop, multi-column responsive dashboard has never been easier. Allows you to build draggable, responsive bootstrap v4-friendly layouts. It also has multiple bindings and works great with React, Angular, Knockout.js, Ember and others. Includes Typescript defines.
Inspired by no-longer maintained gridster, built with love.
Please visit http://gridstackjs.com and these demos.
If you find this lib useful, please donate PayPal or Venmo (adumesny) and help support it!
Join us on Slack: https://gridstackjs.troolee.com
Table of Contents generated with DocToc
- Demo and examples
- Usage
- Install
- Include
- Basic usage
- Requirements
- API Documentation
- Extend Library
- gridstack.js for specific frameworks
- Change grid columns
- Custom columns CSS
- Override resizable/draggable options
- Touch devices support
- Migrating to v0.6
- Migrating to v1
- jQuery Application
- Migrating to v2
- Changes
- The Team
Demo and examples
====
Please visit http://gridstackjs.com and these demos
Usage
=====
js
yarn add gridstack
// or
npm install --save gridstack
`
Include
ES6 or Typescript
`js
import { GridStack } from 'gridstack';
import 'gridstack/dist/gridstack.css';
`
legacy javascript. If you need to import individual files (see jquery apps section)
`js
import 'gridstack/dist/gridstack.all.js';
import 'gridstack/dist/gridstack.css';
`
alternatively in html
`html
`
or using CDN (minimized):
`html
`
.map files are included for debugging purposes.
Basic usage
creating items dynamically...
`js
// ...in your HTML
// ...in your script
var grid = GridStack.init();
grid.addWidget('Item 1', {width: 2});
`
... or creating from list
`js
// using serialize data instead of .addWidget()
const serializedData = [
{x: 0, y: 0, width: 2, height: 2},
{x: 2, y: 3, width: 3, height: 1},
{x: 1, y: 3, width: 1, height: 1}
];
grid.load(serializedData);
`
... or DOM created items
`js
// ...in your HTML
Item 1
Item 2 wider
// ...in your script
GridStack.init();
`
see jsfiddle sample as running example too.
Requirements
GridStack no longer requires external dependencies as of v1.0.0 (lodash was removed in v0.5.0 and jquery API in v1.0.0). All you need to include is gridstack.all.js and gridstack.css (layouts are done using CSS column based %).
API Documentation
Documentation can be found here.
Extend Library
You can easily extend or patch gridstack with code like this:
`js
// 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();
`
gridstack.js for specific frameworks
search for 'gridstack' under NPM for latest, more to come...
- vue.js: see demo v3 or demo v2
- ember: ember-gridstack
- AngularJS: gridstack-angular
- Angular8: lb-gridstack
- Rails: gridstack-js-rails
- React: react-gridstack
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
`js
GridStack.init( {column: N} );
`
2) include gridstack-extra.css if N < 12 (else custom CSS - see next). Without these, things will not render/work correctly.
`html
...
`
Note: we added grid-stack-N class and gridstack-extra.css which defines CSS for grids with custom [1-12] 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
If you need > 12 columns or want to generate the CSS manually you will need to generate CSS rules for .grid-stack-item[data-gs-width="X"] and .grid-stack-item[data-gs-x="X"].
For instance for 3-column grid you need to rewrite CSS to be:
`css
.grid-stack-item[data-gs-width="3"] { width: 100% }
.grid-stack-item[data-gs-width="2"] { width: 66.66666667% }
.grid-stack-item[data-gs-width="1"] { width: 33.33333333% }
.grid-stack-item[data-gs-x="2"] { left: 66.66666667% }
.grid-stack-item[data-gs-x="1"] { left: 33.33333333% }
`
For 4-column grid it should be:
`css
.grid-stack-item[data-gs-width="4"] { width: 100% }
.grid-stack-item[data-gs-width="3"] { width: 75% }
.grid-stack-item[data-gs-width="2"] { width: 50% }
.grid-stack-item[data-gs-width="1"] { width: 25% }
.grid-stack-item[data-gs-x="3"] { left: 75% }
.grid-stack-item[data-gs-x="2"] { left: 50% }
.grid-stack-item[data-gs-x="1"] { left: 25% }
`
and so on.
Better yet, here is a SASS code snippet which can make life much easier (Thanks to @ascendantofrain, #81 and @StefanM98, #868) and you can use sites like sassmeister.com to generate the CSS for you instead:
`sass
.grid-stack > .grid-stack-item {
$gridstack-columns: 12;
min-width: (100% / $gridstack-columns);
@for $i from 1 through $gridstack-columns {
&[data-gs-width='#{$i}'] { width: (100% / $gridstack-columns) * $i; }
&[data-gs-x='#{$i}'] { left: (100% / $gridstack-columns) * $i; }
&[data-gs-min-width='#{$i}'] { min-width: (100% / $gridstack-columns) * $i; }
&[data-gs-max-width='#{$i}'] { max-width: (100% / $gridstack-columns) * $i; }
}
}
`
you can also use the SASS src/gridstack-extra.scss included in NPM package and modify to add more columns
and also have the .grid-stack-N prefix to support letting the user change columns dynamically.
Sample gulp command for 30 columns:
`js
gulp.src('node_modules/gridstack/dist/src/gridstack-extra.scss')
.pipe(replace('$gridstack-columns: 11 !default;','$gridstack-columns: 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:
`js
GridStack.init({
resizable: {
handles: 'e, se, s, sw, w'
}
});
`
Note: It's not recommended to enable nw, n, ne resizing handles. Their behavior may be unexpected.
Touch devices support
Please use jQuery UI Touch Punch to make jQuery UI Draggable/Resizable
working on touch-based devices.
`html
`
Also alwaysShowResizeHandle option may be useful:
`js
let options = {
alwaysShowResizeHandle: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
};
GridStack.init(options);
`
If you're still experiencing issues on touch devices please check #444
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 Migrating to v0.6 if you didn't already
2. your code only needs to 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 below.
3. code change:
OLD initializing code + adding a widget + adding an event:
`js
// 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 Typescript use window.GridStack.init() until next native 2.x TS version
var grid = GridStack.init(opts?, element?);
// returns DOM element
grid.addWidget(' test ', {width: 2});
// event handler
grid.on('added', function(e, items) {/ items contains info /});
// grid access after init
var grid = el.gridstack; // where el = document.querySelector('.grid-stack') or other ways...
`
Other changes
`
GridStackUI --> GridStack
GridStackUI.GridStackEngine --> GridStack.Engine
grid.container (jquery grid wrapper) --> grid.el (grid DOM element)
grid.grid (GridStackEngine) --> grid.engine
grid.setColumn(N) --> grid.column(N) and new grid.column() to get value, old API still supported though
`
Recommend looking at the many samples for more code examples.
$3
We're working on implementing HTML5 drag'n'drop through the plugin system. Right now it is still jquery-ui based. Because of that we are still bundling jquery (3.5.1) + jquery-ui (1.12.1 minimal drag|drop|resize) internally in gridstack.all.js. IFF your app needs to bring your own version instead, you should instead include gridstack-poly.min.js (optional IE support) + gridstack.min.js + gridstack.jQueryUI.min.js after you import your JQ libs. But note that there are issue with jQuery and ES6 import (see 1306).
Note: v2.0.0 does not currently support importing GridStack Drag&Drop without also including our jquery + jqueryui. Still trying to figure how to make that bundle possible. You will have to use 1.x
As for events, you can still use $(".grid-stack").on(...) while jqueryui is used internally for things we don't support, but recommended you don't as that will get dropped at some point.
Migrating to v2
make sure to read v1 migration first!
v2.x is a Typescript rewrite of 1.x, removing all jquery events, using classes and overall code cleanup to support ES6 modules. Your code might need to change from 1.x
1. In general methods that used no args (getter) vs setter can't be used in TS when the arguments differ (set/get are also not function calls so API would have changed). Instead we decided to have all set methods return GridStack to they can be chain-able (ex: grid.float(true).cellHeight(10).column(6)). Also legacy methods that used to take many parameters will now take a single object (typically GridStackOptions or GridStackWidget).
`
addWidget(el, x, y, width, height) --> addWidget(el, {with: 2})
float() to get value --> getFloat()
'cellHeight() to get value --> getCellHeight()
to get value --> getMargin()
`
2. event signatures are generic and not jquery-ui dependent anymore. gsresizestop has been removed as resizestop|dragstop are now called after the DOM attributes have been updated.
3. oneColumnMode would trigger when window.width < 768px by default. We now check for grid width instead (more correct and supports nesting). You might need to adjust grid minWidth or disableOneColumnMode`.