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 and help support it!
Join us on Slack: https://gridstackjs.troolee.com
Table of Contents generated with DocToc
Please visit http://gridstackjs.com and these demos
- Using yarn / npm:
yarn install gridstack
or
npm install --save gridstack- local:
<link rel="stylesheet" href="gridstack.min.css" />
<script src="gridstack.all.js"></script>- Using CDN (minimized):
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/gridstack.min.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gridstack.all.js"></script>if you need to debug, look at the git demo/ examples for non min includes.
creating items dynamically...
<div class="grid-stack"></div>
<script type="text/javascript">
var grid = GridStack.init();
grid.addWidget('<div class="grid-stack-item"><div class="grid-stack-item-content"> test </div></div>', {width: 2});
</script>... or DOM created items
<div class="grid-stack">
<div class="grid-stack-item">
<div class="grid-stack-item-content">Item 1</div>
</div>
<div class="grid-stack-item" data-gs-width="2">
<div class="grid-stack-item-content">Item 2 wider</div>
</div>
</div>
<script type="text/javascript">
GridStack.init();
</script>see jsfiddle sample as running example too.
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 %).
Documentation can be found here.
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.grid.nodes.length + ' items');
};
var grid = GridStack.init();
// you can now call
grid.printCount();search for 'gridstack' under NPM for latest, more to come...
- ember: ember-gridstack
- AngularJS: gridstack-angular
- Angular8: lb-gridstack
- Rails: gridstack-js-rails
- React: react-gridstack
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:
- Change the
columngrid option when creating a grid to your number N
GridStack.init( {column: N} );- include
gridstack-extra.cssif N < 12 (else custom CSS - see next). Without these, things will not render/work correctly.
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/gridstack-extra.css"/>
<div class="grid-stack grid-stack-N">...</div>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
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:
.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:
.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:
.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 look at the SASS src/gridstack-extra.scss and modify to add more columns
and also have the .grid-stack-N prefix to support letting the user change columns dynamically.
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'
}
});Note: It's not recommended to enable nw, n, ne resizing handles. Their behavior may be unexpected.
Please use jQuery UI Touch Punch to make jQuery UI Draggable/Resizable working on touch-based devices.
<script src="gridstack.all.js"></script>
<script src="jquery.ui.touch-punch.min.js"></script>Also alwaysShowResizeHandle option may be useful:
var 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
v1.0.0 removed Jquery from the API and external dependencies, which will require some code changes. Here is a list of the changes:
-
your code only needs to include
gridstack.all.jsandgristack.css(don't include other) and is recommended you do that as internal dependencies will change. Right now jquery+jquery-ui (trimmed versions) are still being used internally for a short while. -
code change:
OLD initializing code + adding a widget + adding an event:
// initialization returned Jquery element, requiring second call to get GridStack var
$('.grid-stack').gridstack(opts?);
var grid = $('.grid-stack').data('gridstack');
// returned Jquery element
grid.addWidget($('<div><div class="grid-stack-item-content"> test </div></div>'), {width: 2});
// jquery event handler
$('.grid-stack').on('added', function(e, items) {/* items contains info */});NEW
// element identifier defaults to '.grid-stack', returns the grid
// Note: for Typescript use window.GridStack.init() until next native TS version
var grid = GridStack.init(opts?, element?);
// returns DOM element
grid.addWidget('<div><div class="grid-stack-item-content"> test </div></div>', {width: 2});
// event handler
grid.on('added', function(e, items) {/* items contains info */});Other vars/global 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.
We're working on implementing support for other drag'n'drop libraries through the plugin system. Right now it is still jquery-ui based (but minimal build content)
View our change log here.
gridstack.js is currently maintained by Dylan Weiss and Alain Dumesny, originally created by Pavel Reznikov. We appreciate all contributors for help.