gridstack.js is a jQuery plugin for widget layout. This is drag-and-drop multi-column grid. It allows you to build draggable responsive bootstrap v3 friendly layouts. It also works great with knockout.js, angular.js and touch devices.
Inspired by gridster.js. Built with love.
Join gridstack.js on Slack: https://gridstackjs.troolee.com
Table of Contents generated with DocToc
- Demo
- Usage
- Requirements
- Install
- Basic usage
- Migrating to v0.2.5
- API Documentation
- Touch devices support
- Use with knockout.js
- Use with angular.js
- Rails integration
- Change grid width
- Extra CSS
- Save grid to array
- Load grid from array
- Override resizable/draggable options
- IE8 support
- Nested grids
- Resizing active grid
- Using AniJS
- The Team
- Changes - v0.2.5-dev (Development version) - v0.2.4 (2016-02-15) - v0.2.3 (2015-06-23) - v0.2.2 (2014-12-23) - v0.2.1 (2014-12-09) - v0.2.0 (2014-11-30) - v0.1.0 (2014-11-18)
- License
Please visit http://troolee.github.io/gridstack.js/ for demo.
- lodash.js (>= 3.5.0)
- jQuery (>= 1.11.0)
- jQuery UI (>= 1.11.0). Minimum required components: Core, Widget, Mouse, Draggable, Resizable
- (Optional) jquery-ui-touch-punch for touch-based devices support
Note: You can still use underscore.js (>= 1.7.0) instead of lodash.js
- Using CDN:
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.2.4/gridstack.min.css" />
<script type="text/javascript" src='//cdnjs.cloudflare.com/ajax/libs/gridstack.js/0.2.4/gridstack.min.js'></script>
- Using bower:
$ bower install gridstack
- Using npm:
$ npm install gridstack
You can download files from dist
directory as well.
<div class="grid-stack">
<div class="grid-stack-item"
data-gs-x="0" data-gs-y="0"
data-gs-width="4" data-gs-height="2">
<div class="grid-stack-item-content"></div>
</div>
<div class="grid-stack-item"
data-gs-x="4" data-gs-y="0"
data-gs-width="4" data-gs-height="4">
<div class="grid-stack-item-content"></div>
</div>
</div>
<script type="text/javascript">
$(function () {
var options = {
cellHeight: 80,
verticalMargin: 10
};
$('.grid-stack').gridstack(options);
});
</script>
As of v0.2.5 all methods and parameters are in camel case to respect JavaScript Style Guide and Coding Conventions. All old methods and parameters are marked as deprecated and still available but a warning will be displayed in js console. They will be available until v1.0 when they will be completely removed.
Please check out doc/README.md
for more information about gridstack.js API.
Please use jQuery UI Touch Punch to make jQuery UI Draggable/Resizable working on touch-based devices.
<script src="lodash.min.js"></script>
<script src="jquery.min.js"></script>
<script src="jquery-ui.min.js"></script>
<script src="jquery.ui.touch-punch.min.js"></script>
<script src="gridstack.js"></script>
Also alwaysShowResizeHandle
option may be useful:
$(function () {
var options = {
alwaysShowResizeHandle: /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
};
$('.grid-stack').gridstack(options);
});
ko.components.register('dashboard-grid', {
viewModel: {
createViewModel: function (controller, componentInfo) {
var ViewModel = function (controller, componentInfo) {
var grid = null;
this.widgets = controller.widgets;
this.afterAddWidget = function (items) {
if (grid == null) {
grid = $(componentInfo.element).find('.grid-stack').gridstack({
auto: false
}).data('gridstack');
}
var item = _.find(items, function (i) { return i.nodeType == 1 });
grid.addWidget(item);
ko.utils.domNodeDisposal.addDisposeCallback(item, function () {
grid.removeWidget(item);
});
};
};
return new ViewModel(controller, componentInfo);
}
},
template:
[
'<div class="grid-stack" data-bind="foreach: {data: widgets, afterRender: afterAddWidget}">',
' <div class="grid-stack-item" data-bind="attr: {\'data-gs-x\': $data.x, \'data-gs-y\': $data.y, \'data-gs-width\': $data.width, \'data-gs-height\': $data.height, \'data-gs-auto-position\': $data.autoPosition}">',
' <div class="grid-stack-item-content">...</div>',
' </div>',
'</div> '
].join('')
});
$(function () {
var Controller = function (widgets) {
this.widgets = ko.observableArray(widgets);
};
var widgets = [
{x: 0, y: 0, width: 2, height: 2},
{x: 2, y: 0, width: 4, height: 2},
{x: 6, y: 0, width: 2, height: 4},
{x: 1, y: 2, width: 4, height: 2}
];
ko.applyBindings(new Controller(widgets));
});
and HTML:
<div data-bind="component: {name: 'dashboard-grid', params: $data}"></div>
See examples: example 1, example 2.
Notes: It's very important to exclude training spaces after widget template:
template:
[
'<div class="grid-stack" data-bind="foreach: {data: widgets, afterRender: afterAddWidget}">',
' <div class="grid-stack-item" data-bind="attr: {\'data-gs-x\': $data.x, \'data-gs-y\': $data.y, \'data-gs-width\': $data.width, \'data-gs-height\': $data.height, \'data-gs-auto-position\': $data.autoPosition}">',
' ....',
' </div>', // <-- NO SPACE **AFTER** </div>
'</div> ' // <-- NO SPACE **BEFORE** </div>
].join('') // <-- JOIN WITH **EMPTY** STRING
Otherwise addDisposeCallback
won't work.
Please check gridstack-angular
For rails users, integration of gridstack.js and its dependencies can be done through gridstack-js-rails
To change grid width (columns count), to addition to width
option, CSS rules
for .grid-stack-item[data-gs-width="X"]
and .grid-stack-item[data-gs-x="X"]
have to be changed accordingly.
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.
Here is a SASS code snipped which can make life easier (Thanks to @ascendantofrain, #81):
.grid-stack-item {
$gridstack-columns: 12;
@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; }
&.grid-stack-item[data-gs-min-width='#{$i}'] { min-width: (100% / $gridstack-columns) * $i; }
&.grid-stack-item[data-gs-max-width='#{$i}'] { max-width: (100% / $gridstack-columns) * $i; }
}
}
Or you can include gridstack-extra.css
. See below for more details.
There are few extra CSS batteries in gridstack-extra.css
(gridstack-extra.min.css
).
You can use other than 12 grid width:
<div class="grid-stack grid-stack-N">...</div>
$('.grid-stack').gridstack({width: N});
See example: 2 grids demo
Because gridstack doesn't track any kind of user-defined widget id there is no reason to make serialization to be part
of gridstack API. To serialize grid you can simply do something like this (let's say you store widget id inside data-custom-id
attribute):
var res = _.map($('.grid-stack .grid-stack-item:visible'), function (el) {
el = $(el);
var node = el.data('_gridstack_node');
return {
id: el.attr('data-custom-id'),
x: node.x,
y: node.y,
width: node.width,
height: node.height
};
});
alert(JSON.stringify(res));
See example: Serialization demo
You can also use onchange
event if you need to save only changed widgets right away they have been changed.
var serialization = [
{x: 0, y: 0, width: 2, height: 2},
{x: 3, y: 1, width: 1, height: 2},
{x: 4, y: 1, width: 1, height: 1},
{x: 2, y: 3, width: 3, height: 1},
{x: 1, y: 4, width: 1, height: 1},
{x: 1, y: 3, width: 1, height: 1},
{x: 2, y: 4, width: 1, height: 1},
{x: 2, y: 5, width: 1, height: 1}
];
serialization = GridStackUI.Utils.sort(serialization);
var grid = $('.grid-stack').data('gridstack');
grid.removeAll();
_.each(serialization, function (node) {
grid.addWidget($('<div><div class="grid-stack-item-content" /></div>'),
node.x, node.y, node.width, node.height);
});
See example: Serialization demo
If you're using knockout there is no need for such method at all.
You can override default resizable
/draggable
options. For instance to enable other then bottom right resizing handle
you can init gridsack like:
$('.grid-stack').gridstack({
resizable: {
handles: 'e, se, s, sw, w'
}
});
Note: It's not recommended to enable nw
, n
, ne
resizing handles. Their behaviour may be unexpected.
Support of IE8 is quite limited and is not a goal at this time. As far as IE8 doesn't support DOM Level 2 I cannot manipulate with CSS stylesheet dynamically. As a workaround you can do the following:
- Create
gridstack-ie8.css
for your configuration (sample for grid with cell height of 60px can be found here). - Include this CSS:
<!--[if lt IE 9]>
<link rel="stylesheet" href="gridstack-ie8.css"/>
<![endif]-->
- You can use this python script to generate such kind of CSS:
#!/usr/bin/env python
height = 60
margin = 20
N = 100
print '.grid-stack > .grid-stack-item { min-height: %(height)spx }' % {'height': height}
for i in range(N):
h = height * (i + 1) + margin * i
print '.grid-stack > .grid-stack-item[data-gs-height="%(index)s"] { height: %(height)spx }' % {'index': i + 1, 'height': h}
for i in range(N):
h = height * (i + 1) + margin * i
print '.grid-stack > .grid-stack-item[data-gs-min-height="%(index)s"] { min-height: %(height)spx }' % {'index': i + 1, 'height': h}
for i in range(N):
h = height * (i + 1) + margin * i
print '.grid-stack > .grid-stack-item[data-gs-max-height="%(index)s"] { max-height: %(height)spx }' % {'index': i + 1, 'height': h}
for i in range(N):
h = height * i + margin * i
print '.grid-stack > .grid-stack-item[data-gs-y="%(index)s"] { top: %(height)spx }' % {'index': i , 'height': h}
There are at least two more issues with gridstack in IE8 with jQueryUI resizable (it seems it doesn't work) and droppable. If you have any suggestions about support of IE8 you are welcome here: gridstack#76
Gridstack may be nested. All nested grids have an additional class grid-stack-nested
which is assigned automatically
during initialization.
See example: Nested grid demo
Resizing on-the-fly is possible, though experimental. This may be used to make gridstack responsive. gridstack will change the total number of columns and will attempt to update the width and x values of each widget to be more logical. See example: Responsive grid demo
Using AniJS with gridstack is a breeze. In the following example, a listener is added that gets triggered by a widget being added. See widgets wiggle! AniJS demo
gridstack.js is currently maintained by Pavel Reznikov, Dylan Weiss and Kevin Dietrich. And we appreciate all contributors for help.
- update names to respect js naming convention.
cellHeight
andverticalMargin
can now be string (e.g. '3em', '20px') (Thanks to @jlowcs).- add
maxWidth
/maxHeight
methods. - add
enableMove
/enableResize
methods. - fix window resize issue #331.
- add options
disableDrag
anddisableResize
. - fix
batchUpdate
/commit
(Thank to @radiolips) - remove dependency of FontAwesome
- RTL support
'auto'
value forcellHeight
option- fix
setStatic
method - add
setAnimation
method to API - add
setGridWidth
method (#227) - add
removable
/removeTimeout
- add
detachGrid
parameter todestroy
method (#216) (thanks @jhpedemonte) - add
useOffset
parameter togetCellFromPixel
method (#237) - add
minWidth
,maxWidth
,minHeight
,maxHeight
,id
parameters toaddWidget
(#188) - add
added
andremoved
events for when a widget is added or removed, respectively. (#54)
- fix closure compiler/linter warnings
- add
static_grid
option. - add
min_width
/min_height
methods (Thanks to @cvillemure) - add
destroy
method (Thanks to @zspitzer) - add
placeholder_text
option (Thanks to @slauyama) - add
handle_class
option. - add
make_widget
method. - lodash v 4.x support (Thanks to @andrewr88)
- gridstack-extra.css
- add support of lodash.js
- add
is_area_empty
method - nested grids
- add
batch_update
/commit
methods - add
update
method - allow to override
resizable
/draggable
options - add
disable
/enable
methods - add
get_cell_from_pixel
(thanks to @juchi) - AMD support
- fix nodes sorting
- improved touch devices support
- add
always_show_resize_handle
option - minor fixes and improvements
- fix grid initialization
- add
cell_height
/cell_width
API methods - fix boolean attributes (issue #31)
- add widgets locking (issue #19)
- add
will_it_fit
API method - fix auto-positioning (issue #20)
- add animation (thanks to @ishields)
- fix
y
coordinate calculation when dragging (issue #18) - fix
remove_widget
(issue #16) - minor fixes
- add
height
option - auto-generate css rules (widgets
height
andtop
) - add
GridStackUI.Utils.sort
utility function - add
remove_all
API method - add
resize
andmove
API methods - add
resizable
andmovable
API methods - add
data-gs-no-move
attribute - add
float
option - fix default css rule for inner content
- minor fixes
Very first version.
The MIT License (MIT)
Copyright (c) 2014-2016 Pavel Reznikov
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.