Repository files navigation

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 withAngular (included),React,Vue,Knockout.js,Ember and others (seeframeworks section).

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

Checkhttp://gridstackjs.com andthese demos.

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

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

Table of Contentsgenerated withDocToc

• Demo and API Documentation
• Usage
  • Install
  • Include
  • Basic usage
  • Requirements
  • Specific frameworks
  • Extend Library
  • Extend Engine
  • Change grid columns
  • Custom columns CSS
  • 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
• jQuery Application
• Changes
• Usage Trend
• The Team

Please visithttp://gridstackjs.com andthese demos, and completeAPI documentation

yarnaddgridstack// ornpminstall--savegridstack

ES6 or Typescript

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

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

<linkhref="node_modules/gridstack/dist/gridstack.min.css"rel="stylesheet"/><scriptsrc="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).You can use the es5 files and polyfill (larger) for older browser instead. For example:

<linkhref="node_modules/gridstack/dist/gridstack.min.css"rel="stylesheet"/><scriptsrc="node_modules/gridstack/dist/es5/gridstack-poly.js"></script><scriptsrc="node_modules/gridstack/dist/es5/gridstack-all.js"></script>

creating items dynamically...

// ...in your HTML<divclass="grid-stack"></div>// ...in your scriptvargrid=GridStack.init();grid.addWidget({w:2,content:'item 1'});

... or creating from list

// using serialize data instead of .addWidget()constserializedData=[{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<divclass="grid-stack"><divclass="grid-stack-item"><divclass="grid-stack-item-content">Item 1</div></div><divclass="grid-stack-item"gs-w="2"><divclass="grid-stack-item-content">Item 2 wider</div></div></div>// ...in your scriptGridStack.init();

...or see list of allAPI and options available.

seejsfiddle sample as running example too.

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 isgridstack-all.js andgridstack.min.css (layouts are done using CSS column based %).

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

• Angular: we ship out of the box an Angular wrapper - seeAngular Component.
• Angular9:lb-gridstack Note: very old v0.3 gridstack instance so recommend forconcept ONLY if you wish to use directive instead. Code hasnot been vented at as I use components.
• AngularJS:gridstack-angular
• Ember:ember-gridstack
• knockout: seedemo using component, but checkcustom bindings ticket which is likely better approach.
• Rails:gridstack-js-rails
• React: work in progress to have wrapper code: seeReact Component. But also seedemo withsrc, orreact-gridstack-example, or read on whathooks to use
• Vue: seedemo withv3 src orv2 src
• Aurelia:aurelia-gridstack, seedemo

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

// extend gridstack with our own custom methodGridStack.prototype.printCount=function(){console.log('grid has '+this.engine.nodes.length+' items');};letgrid=GridStack.init();// you can now callgrid.printCount();

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';classCustomEngineextendsGridStackEngine{/** refined this to move the node to the given new location */publicoverridemoveNode(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;returnsuper.moveNode(node,o);}}GridStack.registerEngine(CustomEngine);// globally set our custom class

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

1. Change thecolumn grid option when creating a grid to your number N

GridStack.init({column:N});

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

<linkhref="node_modules/gridstack/dist/gridstack.min.css"rel="stylesheet"/><linkhref="node_modules/gridstack/dist/gridstack-extra.min.css"rel="stylesheet"/><divclass="grid-stack">...</div>

Note: class.grid-stack-N will automatically be added and we includegridstack-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

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 likesassmeister.com to generate the CSS for you instead:

$columns:20;@functionfixed($float) {@returnround($float*1000)/1000;// total 2+3 digits being %}.gs-#{$columns} >.grid-stack-item {width:fixed(100%/$columns);@for$ifrom1through$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 SCSSsrc/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'))

You can override defaultresizable/draggable options. For instance to enable other then bottom right resizing handleyou can init gridstack like:

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

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:

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

Seeexample.

starting in 0.6.xchange 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 trackadded|removedevents if you didn't and relied on the old broken behavior.

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

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

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

2. code change:

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

// initialization returned Jquery element, requiring second call to get GridStack varvargrid=$('.grid-stack').gridstack(opts?).data('gridstack');// returned Jquery elementgrid.addWidget($('<div><div> test </div></div>'),undefined,undefined,2,undefined,true);// jquery event handler$('.grid-stack').on('added',function(e,items){/* items contains info */});// grid access after initvargrid=$('.grid-stack').data('gridstack');

NEW

// element identifier defaults to '.grid-stack', returns the grid// Note: for Typescript use window.GridStack.init() until next native 2.x TS versionvargrid=GridStack.init(opts?,element?);// returns DOM elementgrid.addWidget('<div><div> test </div></div>',{width:2});// Note: in 3.x it's ever simpler// grid.addWidget({w:2, content: 'test'})// event handlergrid.on('added',function(e,items){/* items contains info */});// grid access after initvargrid=el.gridstack;// where el = document.querySelector('.grid-stack') or other ways...

Other rename changes

`GridStackUI`-->`GridStack``GridStackUI.GridStackEngine`-->`GridStack.Engine``grid.container`(jquerygridwrapper)-->`grid.el`// (grid DOM element)`grid.grid`(GridStackEngine)-->`grid.engine``grid.setColumn(N)`-->`grid.column(N)`and`grid.column()`// to get value, old API still supported though

Recommend looking at themany samples for more code examples.

make sure to read v1 migration first!

v2 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 haveall set methods returnGridStack 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 (typicallyGridStackOptions orGridStackWidget).

`addWidget(el, x, y, width, height)`-->`addWidget(el, {with: 2})`// Note: in 2.1.x you can now just do addWidget({with: 2, content: "text"})`float()`-->`getFloat()`// to get value`cellHeight()`-->`getCellHeight()`// to get value`verticalMargin`-->`margin`// grid options and API that applies to all 4 sides.`verticalMargin()`-->`getMargin()`// to get value

2. event signatures are generic and not jquery-ui dependent anymore.gsresizestop has been removed asresizestop|dragstop are now calledafter the DOM attributes have been updated.

3. oneColumnMode would trigger whenwindow.width < 768px by default. We now check for grid width instead (more correct and supports nesting). You might need to adjust gridoneColumnSize ordisableOneColumnMode.

Note: 2.x no longer support legacy IE11 and older due to using more compact ES6 output and typecsript native code. You will need to stay at 1.x

make sure to read v2 migration first!

v3 has a new HTML5 drag&drop plugging (63k total, all native code), while still allowing you to use the legacy jquery-ui version instead (188k), or a new static grid version (34k, no user drag&drop but full API support). You will need to decide which version to use asgridstack.all.js no longer exist (same is nowgridstack-jq.js) - seeinclude info.

NOTE: HTML5 version is almost on parity with the old jquery-ui based drag&drop. thecontainment (prevent a child from being dragged outside it's parent) andrevert (not clear what it is for yet) are not yet implemented in initial release of v3.0.0.
Also mobile devices don't support h5drag events (will need to handletouch) whereas v3.2 jq version now now supports out of the box (seev3.2 release)

Breaking changes:

1. include (as mentioned) need to change

2. GridStack.update(el, opt) now takes singleGridStackWidget options instead of only supporting (x,y,w,h) BUT legacy call in JS will continue working the same for now. That method is a complete re-write and does the right constrain and updates now for all the available params.

3. locked(),move(),resize(),minWidth(),minHeight(),maxWidth(),maxHeight() methods are hidden from Typescript (JS can still call for now) as they are just 1 liner wrapper aroundupdate(el, opt) anyway and will go away soon. (ex:move(el, x, y) =>update(el, {x, y}))

4. item attribute likedata-gs-min-width is nowgs-min-w. We removed 'data-' from all attributes, and shorten 'width|height' to just 'w|h' to require less typing and more efficient (2k saved in .js alone!).

5. GridStackWidget used in most APIwidth|height|minWidth|minHeight|maxWidth|maxHeight are now shorterw|h|minW|minH|maxW|maxH as well

make sure to read v3 migration first!

v4 is a complete re-write of the collision and drag in/out heuristics to fix some very long standing request & bugs. It also greatly improved usability. Read the release notes for more detail.

Unlikely Breaking Changes (internal usage):

1. removeTimeout was removed (feedback over trash will be immediate - actual removal still on mouse up)

2. the followingGridStackEngine methods changed (used internally, doesn't affectGridStack public API)

// moved to 3 methods with new option params to support new code and pixel coverage check`collision()`->`collide(), collideAll(), collideCoverage()``moveNodeCheck(node, x, y, w, h)`->`moveNodeCheck(node, opt: GridStackMoveOpts)``isNodeChangedPosition(node, x, y, w, h)`->`changedPosConstrain(node, opt: GridStackMoveOpts)``moveNode(node, x, y, w, h, noPack)`->`moveNode(node, opt: GridStackMoveOpts)`

3. removed old obsolete (v0.6-v1 methods/attrs)getGridHeight(),verticalMargin,data-gs-current-height,locked(),maxWidth(),minWidth(),maxHeight(),minHeight(),move(),resize()

make sure to read v4 migration first!

v5 does not have any breaking changes from v4, but a focus on nested grids in h5 mode:You can now drag in/out of parent into nested child, with new API parameters values. See the release notes.

the API did not really change from v5, but a complete re-write of Drag&Drop to use nativemouseevent (instead of HTML draggable=true which is buggy on Mac Safari, and doesn't work on mobile devices) andtouchevent (mobile), and we no longer have jquery ui option (wasn't working well for nested grids, didn't want to maintain legacy lib).

The main difference is you only need to include gridstack.js and get D&D (desktop and mobile) out of the box for the same size as h5 version.

New addition, no API breakage per say. See release notes about creating sub-grids on the fly.

Possible breaking change if you use nested grid JSON format, or original Angular wrapper, or relied on specific CSS paths. Also target is now ES2020 (see release notes).

• GridStackOptions.subGrid ->GridStackOptions.subGridOpts rename. We now haveGridStackWidget.subGridOpts vsGridStackNode.subGrid (was both types which is error prone)
• GridStackOptions.addRemoveCB ->GridStack.addRemoveCB is now global instead of grid option
• removedGridStackOptions.dragInOptions sinceGridStack.setupDragIn() has it replaced since 4.0
• removeGridStackOptions.minWidth obsolete since 5.1, useoneColumnSize instead
• CSS rules removed.grid-stack prefix for anything already gs based, 12 column (default) now uses.gs-12, extra.css is less than 1/4th it original size!,gs-min|max_w|h attribute no longer written (but read)

New addition - see release notes aboutsizeToContent feature.Possible break:

• GridStack.onParentResize() is now calledonResize() as grid now directly track size change, no longer involving parent per say to tell us anything. Note sure why it was public.

we now support much richer responsive behavior withGridStackOptions.columnOpts including any breakpoint width:column pairs, or automatic column sizing.

breaking change:

• disableOneColumnMode,oneColumnSize have been removed (thought we temporary convert if you have them). usecolumnOpts: { breakpoints: [{w:768, c:1}] } for the same behavior.
• 1 column mode switch is no longer by default (columnOpts is not defined) as too many new users had issues. Instead set it explicitly (see above).
• oneColumnModeDomSort has been removed. Planning to support per column layouts at some future times. TBD

• All instances ofel.innerHTML = 'some content' have been removed for security reason as it opens up some potential for accidental XSS.

• Side panel drag&drop complete rewrite.

• new lazy loading option

Breaking change:

• if your code relies onGridStackWidget.content with real HTML (like a few demos) it is up to you to do this:

// NOTE: REAL apps would sanitize-html or DOMPurify before blinding setting innerHTML. see #2736GridStack.renderCB=function(el:HTMLElement,w:GridStackNode){el.innerHTML=w.content;};

• V11 add newGridStack.renderCB that is called for you to create the widget content (entire GridStackWidget is passed so you can use id or some other field as logic) while GS creates the 2 needed parent divs + classes, unlikeGridStack.addRemoveCB which doesn't create anything for you. Both can be handy for Angular/React/Vue frameworks.
• addWidget(w: GridStackWidget) is now the only supported format, no more string content passing. You will need to create content yourself (GridStack.createWidgetDivs() can be used to create parent divs) then callmakeWidget(el) instead.

Potential breaking change:

• BIG overall to how sidepanel helper drag&drop is done:

1. clone() helper is now passed full HTML element dragged, not an event ongrid-stack-item-content so you can clone or set attr at the top.
2. use any class/structure you want for side panel items (see two.html)
3. GridStack.setupDragIn() now support associating aGridStackWidget for each sidepanel that will be used to define what to create on drop!
4. if noGridStackWidget is defined, the helper will now be inserted as is, and NOT original sidepanel item.
5. support DOM gs- attr as well as gridstacknode JSON (see two.html) alternatives.

This isold and no longer apply to v6+. You'll need to use v5.1.1 and before

import'gridstack/dist/gridstack.min.css';import{GridStack}from'gridstack';import'gridstack/dist/jq/gridstack-dd-jqueryui';

Note:jquery &jquery-ui are imported by name, so you will have to specify their location in your webpack (or equivalent) config file,which means you can possibly bring your own version

alias:{'jquery':'gridstack/dist/jq/jquery.js','jquery-ui':'gridstack/dist/jq/jquery-ui.js','jquery.ui':'gridstack/dist/jq/jquery-ui.js','jquery.ui.touch-punch':'gridstack/dist/jq/jquery.ui.touch-punch.js',},

Alternatively (single combined file) in html

<linkhref="node_modules/gridstack/dist/gridstack.min.css"rel="stylesheet"/><!-- HTML5 drag&drop (70k) --><scriptsrc="node_modules/gridstack/dist/gridstack-h5.js"></script><!-- OR jquery-ui drag&drop (195k) --><scriptsrc="node_modules/gridstack/dist/gridstack-jq.js"></script><!-- OR static grid (40k) --><scriptsrc="node_modules/gridstack/dist/gridstack-static.js"></script>

We have a native HTML5 drag'n'drop through the plugin system (default), but the jquery-ui version can be used instead. It will bundlejquery (3.5.1) +jquery-ui (1.13.1 minimal drag|drop|resize) +jquery-ui-touch-punch (1.0.8 for mobile support) ingridstack-jq.js.

NOTE: in v4, v3: we ES6 module import jquery & jquery-ui by name, so you need to specify location of those .js files, which means you might be able to bring your own version as well. See the include instructions.

NOTE: in v1.x IFF you want to use gridstack-jq instead and your app needs to bring your own JQ version, you shouldinstead includegridstack-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 (see1306).

As for events, you can still use$(".grid-stack").on(...) for the version that uses jquery-ui for things we don't support.

View our change loghere.

Usage Trend of gridstack

gridstack.js is currently maintained byAlain Dumesny, before thatDylan Weiss, originally created byPavel Reznikov. We appreciateall contributors for help.