gridstack v12.4.2

Methods

_updateResizeEvent()

protected _updateResizeEvent(forceRemove): GridStack;

Defined in: gridstack.ts:2085

add or remove the grid element size event handler

Parameters

Parameter	Type	Default value
`forceRemove`	`boolean`	`false`

Returns

_widthOrContainer()

protected _widthOrContainer(forBreakpoint): number;

Defined in: gridstack.ts:955

return our expected width (or parent) , and optionally of window for dynamic column check

Parameters

Parameter	Type	Default value
`forBreakpoint`	`boolean`	`false`

Returns

number

addGrid()

static addGrid(parent, opt): GridStack;

Defined in: gridstack.ts:141

call to create a grid with the given options, including loading any children from JSON structure. This will call GridStack.init(), then grid.load() on any passed children (recursively). Great alternative to calling init() if you want entire grid to come from JSON serialized data, including options.

Parameters

Parameter	Type	Description
`parent`	`HTMLElement`	HTML element parent to the grid
`opt`	`GridStackOptions`	grids options used to initialize the grid, and list of children

Returns

addWidget()

addWidget(w): GridItemHTMLElement;

Defined in: gridstack.ts:432

add a new widget and returns it.

Widget will be always placed even if result height is more than actual grid height. You need to use willItFit() before calling addWidget for additional check. See also makeWidget(el) for DOM element.

Parameters

Parameter	Type	Description
`w`	`GridStackWidget`	GridStackWidget definition. used MakeWidget(el) if you have dom element instead.

Returns

GridItemHTMLElement

Example

const grid = GridStack.init();
grid.addWidget({w: 3, content: 'hello'});

batchUpdate()

batchUpdate(flag): GridStack;

Defined in: gridstack.ts:833

use before calling a bunch of addWidget() to prevent un-necessary relayouts in between (more efficient) and get a single event callback. You will see no changes until batchUpdate(false) is called.

Parameters

Parameter	Type	Default value
`flag`	`boolean`	`true`

Returns

cellHeight()

cellHeight(val?): GridStack;

Defined in: gridstack.ts:904

Update current cell height - see GridStackOptions.cellHeight for format by updating eh Browser CSS variable.

Parameters

Parameter	Type	Description
`val?`	`numberOrString`	the cell height. Options: - `undefined`: cells content will be made square (match width minus margin) - `0`: the CSS will be generated by the application instead - number: height in pixels - string: height with units (e.g., '70px', '5rem', '2em')

Returns

the grid instance for chaining

Example

grid.cellHeight(100);     // 100px height
grid.cellHeight('70px');  // explicit pixel height
grid.cellHeight('5rem');  // relative to root font size
grid.cellHeight(grid.cellWidth() * 1.2); // aspect ratio
grid.cellHeight('auto');  // auto-size based on content

cellWidth()

cellWidth(): number;

Defined in: gridstack.ts:950

Gets the current cell width in pixels. This is calculated based on the grid container width divided by the number of columns.

Returns

number

the cell width in pixels

Example

const width = grid.cellWidth();
console.log('Cell width:', width, 'px');

// Use cell width to calculate widget dimensions
const widgetWidth = width * 3; // For a 3-column wide widget

checkDynamicColumn()

protected checkDynamicColumn(): boolean;

Defined in: gridstack.ts:962

checks for dynamic column count for our current size, returning true if changed

Returns

boolean

column()

column(column, layout): GridStack;

Defined in: gridstack.ts:1041

Set the number of columns in the grid. Will update existing widgets to conform to new number of columns, as well as cache the original layout so you can revert back to previous positions without loss.

Requires gridstack-extra.css or gridstack-extra.min.css for [2-11] columns, else you will need to generate correct CSS. See: https://github.com/gridstack/gridstack.js#change-grid-columns

Parameters

Parameter	Type	Default value	Description
`column`	`number`	`undefined`	Integer > 0 (default 12)
`layout`	`ColumnOptions`	`'moveScale'`	specify the type of re-layout that will happen. Options: - 'moveScale' (default): scale widget positions and sizes - 'move': keep widget sizes, only move positions - 'scale': keep widget positions, only scale sizes - 'none': don't change widget positions or sizes Note: items will never be outside of the current column boundaries. Ignored for `column=1` as we always want to vertically stack.

Returns

the grid instance for chaining

Example

// Change to 6 columns with default scaling
grid.column(6);

// Change to 4 columns, only move positions
grid.column(4, 'move');

// Single column layout (vertical stack)
grid.column(1);

compact()

compact(layout, doSort): GridStack;

Defined in: gridstack.ts:1007

Re-layout grid items to reclaim any empty space. This is useful after removing widgets or when you want to optimize the layout.

Parameters

Parameter	Type	Default value	Description
`layout`	`CompactOptions`	`'compact'`	layout type. Options: - 'compact' (default): might re-order items to fill any empty space - 'list': keep the widget left->right order the same, even if that means leaving an empty slot if things don't fit
`doSort`	`boolean`	`true`	re-sort items first based on x,y position. Set to false to do your own sorting ahead (default: true)

Returns

the grid instance for chaining

Example

// Compact layout after removing widgets
grid.removeWidget('.widget-to-remove');
grid.compact();

// Use list layout (preserve order)
grid.compact('list');

// Compact without sorting first
grid.compact('compact', false);

createWidgetDivs()

createWidgetDivs(n): HTMLElement;

Defined in: gridstack.ts:478

Create the default grid item divs and content (possibly lazy loaded) by using GridStack.renderCB().

Parameters

Parameter	Type	Description
`n`	`GridStackNode`	GridStackNode definition containing widget configuration

Returns

HTMLElement

the created HTML element with proper grid item structure

Example

const element = grid.createWidgetDivs({ w: 2, h: 1, content: 'Hello World' });

destroy()

destroy(removeDOM): GridStack;

Defined in: gridstack.ts:1115

Destroys a grid instance. DO NOT CALL any methods or access any vars after this as it will free up members.

Parameters

Parameter	Type	Default value	Description
`removeDOM`	`boolean`	`true`	if `false` grid and items HTML elements will not be removed from the DOM (Optional. Default `true`).

Returns

disable()

disable(recurse): GridStack;

Defined in: gridstack.ts:2286

Temporarily disables widgets moving/resizing. If you want a more permanent way (which freezes up resources) use setStatic(true) instead.

Note: This is a no-op for static grids.

This is a shortcut for:

grid.enableMove(false);
grid.enableResize(false);

Parameters

Parameter	Type	Default value	Description
`recurse`	`boolean`	`true`	if true (default), sub-grids also get updated

Returns

the grid instance for chaining

Example

// Disable all interactions
grid.disable();

// Disable only this grid, not sub-grids
grid.disable(false);

enable()

enable(recurse): GridStack;

Defined in: gridstack.ts:2313

Re-enables widgets moving/resizing - see disable(). Note: This is a no-op for static grids.

This is a shortcut for:

grid.enableMove(true);
grid.enableResize(true);

Parameters

Parameter	Type	Default value	Description
`recurse`	`boolean`	`true`	if true (default), sub-grids also get updated

Returns

the grid instance for chaining

Example

// Re-enable all interactions
grid.enable();

// Enable only this grid, not sub-grids
grid.enable(false);

enableMove()

enableMove(doEnable, recurse): GridStack;

Defined in: gridstack.ts:2339

Enables/disables widget moving for all widgets. No-op for static grids. Note: locally defined items (with noMove property) still override this setting.

Parameters

Parameter	Type	Default value	Description
`doEnable`	`boolean`	`undefined`	if true widgets will be movable, if false moving is disabled
`recurse`	`boolean`	`true`	if true (default), sub-grids also get updated

Returns

the grid instance for chaining

Example

// Enable moving for all widgets
grid.enableMove(true);

// Disable moving for all widgets
grid.enableMove(false);

// Enable only this grid, not sub-grids
grid.enableMove(true, false);

enableResize()

enableResize(doEnable, recurse): GridStack;

Defined in: gridstack.ts:2367

Enables/disables widget resizing for all widgets. No-op for static grids. Note: locally defined items (with noResize property) still override this setting.

Parameters

Parameter	Type	Default value	Description
`doEnable`	`boolean`	`undefined`	if true widgets will be resizable, if false resizing is disabled
`recurse`	`boolean`	`true`	if true (default), sub-grids also get updated

Returns

the grid instance for chaining

Example

// Enable resizing for all widgets
grid.enableResize(true);

// Disable resizing for all widgets
grid.enableResize(false);

// Enable only this grid, not sub-grids
grid.enableResize(true, false);

float()

float(val): GridStack;

Defined in: gridstack.ts:1149

Enable/disable floating widgets (default: false). When enabled, widgets can float up to fill empty spaces. See example

Parameters

Parameter	Type	Description
`val`	`boolean`	true to enable floating, false to disable

Returns

the grid instance for chaining

Example

grid.float(true);  // Enable floating
grid.float(false); // Disable floating (default)

getCellFromPixel()

getCellFromPixel(position, useDocRelative): CellPosition;

Defined in: gridstack.ts:1179

Get the position of the cell under a pixel on screen.

Parameters

Parameter	Type	Default value	Description
`position`	`MousePosition`	`undefined`	the position of the pixel to resolve in absolute coordinates, as an object with top and left properties
`useDocRelative`	`boolean`	`false`	if true, value will be based on document position vs parent position (Optional. Default false). Useful when grid is within `position: relative` element Returns an object with properties `x` and `y` i.e. the column and row in the grid.

Returns

CellPosition

getCellHeight()

getCellHeight(forcePixel): number;

Defined in: gridstack.ts:857

Gets the current cell height in pixels. This takes into account the unit type and converts to pixels if necessary.

Parameters

Parameter	Type	Default value	Description
`forcePixel`	`boolean`	`false`	if true, forces conversion to pixels even when cellHeight is specified in other units

Returns

number

the cell height in pixels

Example

const height = grid.getCellHeight();
console.log('Cell height:', height, 'px');

// Force pixel conversion
const pixelHeight = grid.getCellHeight(true);

getColumn()

getColumn(): number;

Defined in: gridstack.ts:1078

Get the number of columns in the grid (default 12).

Returns

number

the current number of columns in the grid

Example

const columnCount = grid.getColumn(); // returns 12 by default

getDD()

static getDD(): DDGridStack;

Defined in: gridstack.ts:2183

Get the global drag & drop implementation instance. This provides access to the underlying drag & drop functionality.

Returns

the DDGridStack instance used for drag & drop operations

Example

const dd = GridStack.getDD();
// Access drag & drop functionality

getFloat()

getFloat(): boolean;

Defined in: gridstack.ts:1166

Get the current float mode setting.

Returns

boolean

true if floating is enabled, false otherwise

Example

const isFloating = grid.getFloat();
console.log('Floating enabled:', isFloating);

getGridItems()

getGridItems(): GridItemHTMLElement[];

Defined in: gridstack.ts:1092

Returns an array of grid HTML elements (no placeholder) - used to iterate through our children in DOM order. This method excludes placeholder elements and returns only actual grid items.

Returns

GridItemHTMLElement[]

array of GridItemHTMLElement instances representing all grid items

Example

const items = grid.getGridItems();
items.forEach(item => {
  console.log('Item ID:', item.gridstackNode.id);
});

getMargin()

getMargin(): number;

Defined in: gridstack.ts:1791

Returns the current margin value as a number (undefined if the 4 sides don't match). This only returns a number if all sides have the same margin value.

Returns

number

the margin value in pixels, or undefined if sides have different values

Example

const margin = grid.getMargin();
if (margin !== undefined) {
  console.log('Uniform margin:', margin, 'px');
} else {
  console.log('Margins are different on different sides');
}

getRow()

getRow(): number;

Defined in: gridstack.ts:1209

Returns the current number of rows, which will be at least minRow if set. The row count is based on the highest positioned widget in the grid.

Returns

number

the current number of rows in the grid

Example

const rowCount = grid.getRow();
console.log('Grid has', rowCount, 'rows');

init()

static init(options, elOrString): GridStack;

Defined in: gridstack.ts:91

initializing the HTML element, or selector string, into a grid will return the grid. Calling it again will simply return the existing instance (ignore any passed options). There is also an initAll() version that support multiple grids initialization at once. Or you can use addGrid() to create the entire grid from JSON.

Parameters

Parameter	Type	Default value	Description
`options`	`GridStackOptions`	`{}`	grid options (optional)
`elOrString`	`GridStackElement`	`'.grid-stack'`	element or CSS selector (first one used) to convert to a grid (default to '.grid-stack' class selector)

Returns

Example

const grid = GridStack.init();

Note: the HTMLElement (of type GridHTMLElement) will store a `gridstack: GridStack` value that can be retrieve later
const grid = document.querySelector('.grid-stack').gridstack;

initAll()

static initAll(options, selector): GridStack[];

Defined in: gridstack.ts:118

Will initialize a list of elements (given a selector) and return an array of grids.

Parameters

Parameter	Type	Default value	Description
`options`	`GridStackOptions`	`{}`	grid options (optional)
`selector`	`string`	`'.grid-stack'`	elements selector to convert to grids (default to '.grid-stack' class selector)

Returns

GridStack[]

Example

const grids = GridStack.initAll();
grids.forEach(...)

isAreaEmpty()

isAreaEmpty(
   x, 
   y, 
   w, 
   h): boolean;

Defined in: gridstack.ts:1228

Checks if the specified rectangular area is empty (no widgets occupy any part of it).

Parameters

Parameter	Type	Description
`x`	`number`	the x coordinate (column) of the area to check
`y`	`number`	the y coordinate (row) of the area to check
`w`	`number`	the width in columns of the area to check
`h`	`number`	the height in rows of the area to check

Returns

boolean

true if the area is completely empty, false if any widget overlaps

Example

// Check if a 2x2 area at position (1,1) is empty
if (grid.isAreaEmpty(1, 1, 2, 2)) {
  console.log('Area is available for placement');
}

isIgnoreChangeCB()

isIgnoreChangeCB(): boolean;

Defined in: gridstack.ts:1109

Returns true if change callbacks should be ignored due to column change, sizeToContent, loading, etc. This is useful for callers who want to implement dirty flag functionality.

Returns

boolean

true if change callbacks are currently being ignored

Example

if (!grid.isIgnoreChangeCB()) {
  // Process the change event
  console.log('Grid layout changed');
}

load()

load(items, addRemove): GridStack;

Defined in: gridstack.ts:722

Load widgets from a list. This will call update() on each (matching by id) or add/remove widgets that are not there. Used to restore a grid layout for a saved layout list (see save()).

Parameters

Parameter	Type	Description
`items`	`GridStackWidget`[]	list of widgets definition to update/create
`addRemove`	`boolean` \| `AddRemoveFcn`	boolean (default true) or callback method can be passed to control if and how missing widgets can be added/removed, giving the user control of insertion.

Returns

the grid instance for chaining

Example

// Basic usage with saved layout
const savedLayout = grid.save(); // Save current layout
// ... later restore it
grid.load(savedLayout);

// Load with custom add/remove callback
grid.load(layout, (items, grid, add) => {
  if (add) {
    // Custom logic for adding new widgets
    items.forEach(item => {
      const el = document.createElement('div');
      el.innerHTML = item.content || '';
      grid.addWidget(el, item);
    });
  } else {
    // Custom logic for removing widgets
    items.forEach(item => grid.removeWidget(item.el));
  }
});

// Load without adding/removing missing widgets
grid.load(layout, false);

See

http://gridstackjs.com/demo/serialization.html for complete example

makeSubGrid()

makeSubGrid(
   el, 
   ops?, 
   nodeToAdd?, 
   saveContent?): GridStack;

Defined in: gridstack.ts:506

Convert an existing gridItem element into a sub-grid with the given (optional) options, else inherit them from the parent's subGrid options.

Parameters

Parameter	Type	Default value	Description
`el`	`GridItemHTMLElement`	`undefined`	gridItem element to convert
`ops?`	`GridStackOptions`	`undefined`	(optional) sub-grid options, else default to node, then parent settings, else defaults
`nodeToAdd?`	`GridStackNode`	`undefined`	(optional) node to add to the newly created sub grid (used when dragging over existing regular item)
`saveContent?`	`boolean`	`true`	if true (default) the html inside .grid-stack-content will be saved to child widget

Returns

newly created grid

makeWidget()

makeWidget(els, options?): GridItemHTMLElement;

Defined in: gridstack.ts:1256

If you add elements to your grid by hand (or have some framework creating DOM), you have to tell gridstack afterwards to make them widgets. If you want gridstack to add the elements for you, use addWidget() instead. Makes the given element a widget and returns it.

Parameters

Parameter	Type	Description
`els`	`GridStackElement`	widget or single selector to convert.
`options?`	`GridStackWidget`	widget definition to use instead of reading attributes or using default sizing values

Returns

GridItemHTMLElement

the converted GridItemHTMLElement

Example

const grid = GridStack.init();

// Create HTML content manually, possibly looking like:
// <div id="item-1" gs-x="0" gs-y="0" gs-w="3" gs-h="2"></div>
grid.el.innerHTML = '<div id="item-1" gs-w="3"></div><div id="item-2"></div>';

// Convert existing elements to widgets
grid.makeWidget('#item-1'); // Uses gs-* attributes from DOM
grid.makeWidget('#item-2', {w: 2, h: 1, content: 'Hello World'});

// Or pass DOM element directly
const element = document.getElementById('item-3');
grid.makeWidget(element, {x: 0, y: 1, w: 4, h: 2});

margin()

margin(value): GridStack;

Defined in: gridstack.ts:1762

Updates the margins which will set all 4 sides at once - see GridStackOptions.margin for format options. Supports CSS string format of 1, 2, or 4 values or a single number.

Parameters

Parameter	Type	Description
`value`	`numberOrString`	margin value - can be: - Single number: `10` (applies to all sides) - Two values: `'10px 20px'` (top/bottom, left/right) - Four values: `'10px 20px 5px 15px'` (top, right, bottom, left)

Returns

the grid instance for chaining

Example

grid.margin(10);           // 10px all sides
grid.margin('10px 20px');  // 10px top/bottom, 20px left/right
grid.margin('5px 10px 15px 20px'); // Different for each side

movable()

movable(els, val): GridStack;

Defined in: gridstack.ts:2227

Enables/Disables dragging by the user for specific grid elements. For all items and future items, use enableMove() instead. No-op for static grids.

Note: If you want to prevent an item from moving due to being pushed around by another during collision, use the 'locked' property instead.

Parameters

Parameter	Type	Description
`els`	`GridStackElement`	widget element(s) or selector to modify
`val`	`boolean`	if true widget will be draggable, assuming the parent grid isn't noMove or static

Returns

the grid instance for chaining

Example

// Make specific widgets draggable
grid.movable('.my-widget', true);

// Disable dragging for specific widgets
grid.movable('#fixed-widget', false);

off()

off(name): GridStack;

Defined in: gridstack.ts:1352

unsubscribe from the 'on' event GridStackEvent

Parameters

Parameter	Type	Description
`name`	`string`	of the event (see possible values) or list of names space separated

Returns

offAll()

offAll(): GridStack;

Defined in: gridstack.ts:1379

Remove all event handlers from the grid. This is useful for cleanup when destroying a grid.

Returns

the grid instance for chaining

Example

grid.offAll(); // Remove all event listeners

on()

Call Signature

on(name, callback): GridStack;

Defined in: gridstack.ts:1315

Supported events:

added: Called when widgets are being added to a grid
change: Occurs when widgets change their position/size due to constraints or direct changes
disable: Called when grid becomes disabled
dragstart: Called when grid item starts being dragged
drag: Called while grid item is being dragged (for each new row/column value)
dragstop: Called after user is done moving the item, with updated DOM attributes
dropped: Called when an item has been dropped and accepted over a grid
enable: Called when grid becomes enabled
removed: Called when items are being removed from the grid
resizestart: Called before user starts resizing an item
resize: Called while grid item is being resized (for each new row/column value)
resizestop: Called after user is done resizing the item, with updated DOM attributes

Parameters

Parameter	Type	Description
`name`	`"dropped"`	event name(s) to listen for (space separated for multiple)
`callback`	`GridStackDroppedHandler`	function to call when event occurs

Returns

the grid instance for chaining

Example

// Listen to multiple events at once
grid.on('added removed change', (event, items) => {
  items.forEach(item => console.log('Item changed:', item));
});

// Listen to individual events
grid.on('added', (event, items) => {
  items.forEach(item => console.log('Added item:', item));
});

Call Signature

on(name, callback): GridStack;

Defined in: gridstack.ts:1316

Supported events:

added: Called when widgets are being added to a grid
change: Occurs when widgets change their position/size due to constraints or direct changes
disable: Called when grid becomes disabled
dragstart: Called when grid item starts being dragged
drag: Called while grid item is being dragged (for each new row/column value)
dragstop: Called after user is done moving the item, with updated DOM attributes
dropped: Called when an item has been dropped and accepted over a grid
enable: Called when grid becomes enabled
removed: Called when items are being removed from the grid
resizestart: Called before user starts resizing an item
resize: Called while grid item is being resized (for each new row/column value)
resizestop: Called after user is done resizing the item, with updated DOM attributes

Parameters

Parameter	Type	Description
`name`	`"enable"` \| `"disable"`	event name(s) to listen for (space separated for multiple)
`callback`	`GridStackEventHandler`	function to call when event occurs

Returns

the grid instance for chaining

Example

// Listen to multiple events at once
grid.on('added removed change', (event, items) => {
  items.forEach(item => console.log('Item changed:', item));
});

// Listen to individual events
grid.on('added', (event, items) => {
  items.forEach(item => console.log('Added item:', item));
});

Call Signature

on(name, callback): GridStack;

Defined in: gridstack.ts:1317

Supported events:

added: Called when widgets are being added to a grid
change: Occurs when widgets change their position/size due to constraints or direct changes
disable: Called when grid becomes disabled
dragstart: Called when grid item starts being dragged
drag: Called while grid item is being dragged (for each new row/column value)
dragstop: Called after user is done moving the item, with updated DOM attributes
dropped: Called when an item has been dropped and accepted over a grid
enable: Called when grid becomes enabled
removed: Called when items are being removed from the grid
resizestart: Called before user starts resizing an item
resize: Called while grid item is being resized (for each new row/column value)
resizestop: Called after user is done resizing the item, with updated DOM attributes

Parameters

Parameter	Type	Description
`name`	`"change"` \| `"added"` \| `"removed"` \| `"resizecontent"`	event name(s) to listen for (space separated for multiple)
`callback`	`GridStackNodesHandler`	function to call when event occurs

Returns

the grid instance for chaining

Example

// Listen to multiple events at once
grid.on('added removed change', (event, items) => {
  items.forEach(item => console.log('Item changed:', item));
});

// Listen to individual events
grid.on('added', (event, items) => {
  items.forEach(item => console.log('Added item:', item));
});

Call Signature

on(name, callback): GridStack;

Defined in: gridstack.ts:1318

Supported events:

added: Called when widgets are being added to a grid
change: Occurs when widgets change their position/size due to constraints or direct changes
disable: Called when grid becomes disabled
dragstart: Called when grid item starts being dragged
drag: Called while grid item is being dragged (for each new row/column value)
dragstop: Called after user is done moving the item, with updated DOM attributes
dropped: Called when an item has been dropped and accepted over a grid
enable: Called when grid becomes enabled
removed: Called when items are being removed from the grid
resizestart: Called before user starts resizing an item
resize: Called while grid item is being resized (for each new row/column value)
resizestop: Called after user is done resizing the item, with updated DOM attributes

Parameters

Parameter	Type	Description
`name`	\| `"drag"` \| `"dragstart"` \| `"resize"` \| `"resizestart"` \| `"resizestop"` \| `"dragstop"`	event name(s) to listen for (space separated for multiple)
`callback`	`GridStackElementHandler`	function to call when event occurs

Returns

the grid instance for chaining

Example

// Listen to multiple events at once
grid.on('added removed change', (event, items) => {
  items.forEach(item => console.log('Item changed:', item));
});

// Listen to individual events
grid.on('added', (event, items) => {
  items.forEach(item => console.log('Added item:', item));
});

Call Signature

on(name, callback): GridStack;

Defined in: gridstack.ts:1319

Supported events:

added: Called when widgets are being added to a grid
change: Occurs when widgets change their position/size due to constraints or direct changes
disable: Called when grid becomes disabled
dragstart: Called when grid item starts being dragged
drag: Called while grid item is being dragged (for each new row/column value)
dragstop: Called after user is done moving the item, with updated DOM attributes
dropped: Called when an item has been dropped and accepted over a grid
enable: Called when grid becomes enabled
removed: Called when items are being removed from the grid
resizestart: Called before user starts resizing an item
resize: Called while grid item is being resized (for each new row/column value)
resizestop: Called after user is done resizing the item, with updated DOM attributes

Parameters

Parameter	Type	Description
`name`	`string`	event name(s) to listen for (space separated for multiple)
`callback`	`GridStackEventHandlerCallback`	function to call when event occurs

Returns

the grid instance for chaining

Example

// Listen to multiple events at once
grid.on('added removed change', (event, items) => {
  items.forEach(item => console.log('Item changed:', item));
});

// Listen to individual events
grid.on('added', (event, items) => {
  items.forEach(item => console.log('Added item:', item));
});

onResize()

onResize(clientWidth): GridStack;

Defined in: gridstack.ts:2024

called when we are being resized - check if the one Column Mode needs to be turned on/off and remember the prev columns we used, or get our count from parent, as well as check for cellHeight==='auto' (square) or sizeToContent gridItem options.

Parameters

Parameter	Type
`clientWidth`	`number`

Returns

prepareDragDrop()

prepareDragDrop(el, force?): GridStack;

Defined in: gridstack.ts:2710

prepares the element for drag&drop - this is normally called by makeWidget() unless are are delay loading

Parameters

Parameter	Type	Default value	Description
`el`	`GridItemHTMLElement`	`undefined`	GridItemHTMLElement of the widget
`force?`	`boolean`	`false`

Returns

registerEngine()

static registerEngine(engineClass): void;

Defined in: gridstack.ts:172

call this method to register your engine instead of the default one. See instead GridStackOptions.engineClass if you only need to replace just one instance.

Parameters

Parameter	Type
`engineClass`	typeof `GridStackEngine`

Returns

void

removeAll()

removeAll(removeDOM, triggerEvent): GridStack;

Defined in: gridstack.ts:1428

Removes all widgets from the grid.

Parameters

Parameter	Type	Default value	Description
`removeDOM`	`boolean`	`true`	if `false` DOM elements won't be removed from the tree (Default? `true`).
`triggerEvent`	`boolean`	`true`	if `false` (quiet mode) element will not be added to removed list and no 'removed' callbacks will be called (Default? true).

Returns

removeAsSubGrid()

removeAsSubGrid(nodeThatRemoved?): void;

Defined in: gridstack.ts:599

called when an item was converted into a nested grid to accommodate a dragged over item, but then item leaves - return back to the original grid-item. Also called to remove empty sub-grids when last item is dragged out (since re-creating is simple)

Parameters

Parameter	Type
`nodeThatRemoved?`	`GridStackNode`

Returns

void

removeWidget()

removeWidget(
   els, 
   removeDOM, 
   triggerEvent): GridStack;

Defined in: gridstack.ts:1390

Removes widget from the grid.

Parameters

Parameter	Type	Default value	Description
`els`	`GridStackElement`	`undefined`	-
`removeDOM`	`boolean`	`true`	if `false` DOM element won't be removed from the tree (Default? true).
`triggerEvent`	`boolean`	`true`	if `false` (quiet mode) element will not be added to removed list and no 'removed' callbacks will be called (Default? true).

Returns

resizable()

resizable(els, val): GridStack;

Defined in: gridstack.ts:2253

Enables/Disables user resizing for specific grid elements. For all items and future items, use enableResize() instead. No-op for static grids.

Parameters

Parameter	Type	Description
`els`	`GridStackElement`	widget element(s) or selector to modify
`val`	`boolean`	if true widget will be resizable, assuming the parent grid isn't noResize or static

Returns

the grid instance for chaining

Example

// Make specific widgets resizable
grid.resizable('.my-widget', true);

// Disable resizing for specific widgets
grid.resizable('#fixed-size-widget', false);

resizeToContent()

resizeToContent(el): void;

Defined in: gridstack.ts:1652

Updates widget height to match the content height to avoid vertical scrollbars or dead space. This automatically adjusts the widget height based on its content size.

Note: This assumes only 1 child under resizeToContentParent='.grid-stack-item-content' (sized to gridItem minus padding) that represents the entire content size.

Parameters

Parameter	Type	Description
`el`	`GridItemHTMLElement`	the grid item element to resize

Returns

void

Example

// Resize a widget to fit its content
const widget = document.querySelector('.grid-stack-item');
grid.resizeToContent(widget);

// This is commonly used with dynamic content:
widget.querySelector('.content').innerHTML = 'New longer content...';
grid.resizeToContent(widget);

rotate()

rotate(els, relative?): GridStack;

Defined in: gridstack.ts:1727

Rotate widgets by swapping their width and height. This is typically called when the user presses 'r' during dragging. The rotation swaps the w/h dimensions and adjusts min/max constraints accordingly.

Parameters

Parameter	Type	Description
`els`	`GridStackElement`	widget element(s) or selector to rotate
`relative?`	`Position`	optional pixel coordinate relative to upper/left corner to rotate around (keeps that cell under cursor)

Returns

the grid instance for chaining

Example

// Rotate a specific widget
grid.rotate('.my-widget');

// Rotate with relative positioning during drag
grid.rotate(widget, { left: 50, top: 30 });

save()

save(
   saveContent, 
   saveGridOpt, 
   saveCB, 
   column?): 
  | GridStackOptions
  | GridStackWidget[];

Defined in: gridstack.ts:634

saves the current layout returning a list of widgets for serialization which might include any nested grids.

Parameters

Parameter	Type	Default value	Description
`saveContent`	`boolean`	`true`	if true (default) the latest html inside .grid-stack-content will be saved to GridStackWidget.content field, else it will be removed.
`saveGridOpt`	`boolean`	`false`	if true (default false), save the grid options itself, so you can call the new GridStack.addGrid() to recreate everything from scratch. GridStackOptions.children would then contain the widget list instead.
`saveCB`	`SaveFcn`	`GridStack.saveCB`	callback for each node -> widget, so application can insert additional data to be saved into the widget data structure.
`column?`	`number`	`undefined`	if provided, the grid will be saved for the given column size (IFF we have matching internal saved layout, or current layout). Otherwise it will use the largest possible layout (say 12 even if rendering at 1 column) so we can restore to all layouts. NOTE: if you want to save to currently display layout, pass this.getColumn() as column. NOTE2: nested grids will ALWAYS save to the container size to be in sync with parent.

Returns

| GridStackOptions | GridStackWidget[]

list of widgets or full grid option, including .children list of widgets

setAnimation()

setAnimation(doAnimate, delay?): GridStack;

Defined in: gridstack.ts:1447

Toggle the grid animation state. Toggles the grid-stack-animate class.

Parameters

Parameter	Type	Description
`doAnimate`	`boolean`	if true the grid will animate.
`delay?`	`boolean`	if true setting will be set on next event loop.

Returns

setStatic()

setStatic(
   val, 
   updateClass, 
   recurse): GridStack;

Defined in: gridstack.ts:1470

Toggle the grid static state, which permanently removes/add Drag&Drop support, unlike disable()/enable() that just turns it off/on. Also toggle the grid-stack-static class.

Parameters

Parameter	Type	Default value	Description
`val`	`boolean`	`undefined`	if true the grid become static.
`updateClass`	`boolean`	`true`	true (default) if css class gets updated
`recurse`	`boolean`	`true`	true (default) if sub-grids also get updated

Returns

setupDragIn()

static setupDragIn(
   dragIn?, 
   dragInOptions?, 
   widgets?, 
   root?): void;

Defined in: gridstack.ts:2196

call to setup dragging in from the outside (say toolbar), by specifying the class selection and options. Called during GridStack.init() as options, but can also be called directly (last param are used) in case the toolbar is dynamically create and needs to be set later.

Parameters

Parameter	Type	Default value	Description
`dragIn?`	`string` \| `HTMLElement`[]	`undefined`	string selector (ex: '.sidebar-item') or list of dom elements
`dragInOptions?`	`DDDragOpt`	`undefined`	options - see DDDragOpt. (default: {handle: '.grid-stack-item-content', appendTo: 'body'}
`widgets?`	`GridStackWidget`[]	`undefined`	GridStackWidget def to assign to each element which defines what to create on drop
`root?`	`HTMLElement` \| `Document`	`document`	optional root which defaults to document (for shadow dom pass the parent HTMLDocument)

Returns

void

triggerEvent()

protected triggerEvent(event, target): void;

Defined in: gridstack.ts:2964

call given event callback on our main top-most grid (if we're nested)

Parameters

Parameter	Type
`event`	`Event`
`target`	`GridItemHTMLElement`

Returns

void

update()

update(els, opt): GridStack;

Defined in: gridstack.ts:1548

Updates widget position/size and other info. This is used to change widget properties after creation. Can update position, size, content, and other widget properties.

Note: If you need to call this on all nodes, use load() instead which will update what changed. Setting the same x,y for multiple items will be indeterministic and likely unwanted.

Parameters

Parameter	Type	Description
`els`	`GridStackElement`	widget element(s) or selector to modify
`opt`	`GridStackWidget`	new widget options (x,y,w,h, etc.). Only those set will be updated.

Returns

the grid instance for chaining

Example

// Update widget size and position
grid.update('.my-widget', { x: 2, y: 1, w: 3, h: 2 });

// Update widget content
grid.update(widget, { content: '<p>New content</p>' });

// Update multiple properties
grid.update('#my-widget', {
  w: 4,
  h: 3,
  noResize: true,
  locked: true
});

updateOptions()

updateOptions(o): GridStack;

Defined in: gridstack.ts:1488

Updates the passed in options on the grid (similar to update(widget) for for the grid options).

Parameters

Parameter	Type
`o`	`GridStackOptions`

Returns

willItFit()

willItFit(node): boolean;

Defined in: gridstack.ts:1805

Returns true if the height of the grid will be less than the vertical constraint. Always returns true if grid doesn't have height constraint.

Parameters

Parameter	Type	Description
`node`	`GridStackWidget`	contains x,y,w,h,auto-position options

Returns

boolean

Example

if (grid.willItFit(newWidget)) {
  grid.addWidget(newWidget);
} else {
  alert('Not enough free space to place the widget');
}

Properties

Property	Modifier	Type	Default value	Description	Defined in
`addRemoveCB?`	`static`	`AddRemoveFcn`	`undefined`	callback method use when new items	grids needs to be created or deleted, instead of the default item: w.content grid: grid content... add = true: the returned DOM element will then be converted to a GridItemHTMLElement using makeWidget()
`animationDelay`	`public`	`number`	`undefined`	time to wait for animation (if enabled) to be done so content sizing can happen	gridstack.ts:218
`el`	`public`	`GridHTMLElement`	`undefined`	the HTML element tied to this grid after it's been initialized	gridstack.ts:266
`engine`	`public`	`GridStackEngine`	`undefined`	engine used to implement non DOM grid functionality	gridstack.ts:212
`Engine`	`static`	typeof `GridStackEngine`	`GridStackEngine`	scoping so users can call new GridStack.Engine(12) for example	gridstack.ts:209
`engineClass`	`static`	typeof `GridStackEngine`	`undefined`	-	gridstack.ts:220
`opts`	`public`	`GridStackOptions`	`{}`	grid options - public for classes to access, but use methods to modify!	gridstack.ts:266
`parentGridNode?`	`public`	`GridStackNode`	`undefined`	point to a parent grid item if we're nested (inside a grid-item in between 2 Grids)	gridstack.ts:215
`renderCB?`	`static`	`RenderFcn`	`undefined`	callback to create the content of widgets so the app can control how to store and restore it By default this lib will do 'el.textContent = w.content' forcing text only support for avoiding potential XSS issues.	gridstack.ts:195
`resizeObserver`	`protected`	`ResizeObserver`	`undefined`	-	gridstack.ts:221
`resizeToContentCB?`	`static`	`ResizeToContentFcn`	`undefined`	callback to use for resizeToContent instead of the built in one	gridstack.ts:201
`resizeToContentParent`	`static`	`string`	`'.grid-stack-item-content'`	parent class for sizing content. defaults to '.grid-stack-item-content'	gridstack.ts:203
`responseLayout`	`protected`	`ColumnOptions`	`undefined`	-	gridstack.ts:258
`saveCB?`	`static`	`SaveFcn`	`undefined`	callback during saving to application can inject extra data for each widget, on top of the grid layout properties	gridstack.ts:189
`updateCB?`	`static`	(`w`) => `void`	`undefined`	called after a widget has been updated (eg: load() into an existing list of children) so application can do extra work	gridstack.ts:198
`Utils`	`static`	typeof `Utils`	`Utils`	scoping so users can call GridStack.Utils.sort() for example	gridstack.ts:206

GridStackEngine

Defined in: gridstack-engine.ts:34

Defines the GridStack engine that handles all grid layout calculations and node positioning. This is the core engine that performs grid manipulation without any DOM operations.

The engine manages:

Node positioning and collision detection
Layout algorithms (compact, float, etc.)
Grid resizing and column changes
Widget movement and resizing logic

NOTE: Values should not be modified directly - use the main GridStack API instead to ensure proper DOM updates and event triggers.

Accessors

float

Get Signature

get float(): boolean;

Defined in: gridstack-engine.ts:438

Get the current floating mode setting.

Example

const isFloating = engine.float;
console.log('Floating enabled:', isFloating);

Returns

boolean

true if floating is enabled, false otherwise

Set Signature

set float(val): void;

Defined in: gridstack-engine.ts:421

Enable/disable floating widgets (default: false). When floating is enabled, widgets can move up to fill empty spaces. See example

Example

engine.float = true;  // Enable floating
engine.float = false; // Disable floating (default)

Parameters

Parameter	Type	Description
`val`	`boolean`	true to enable floating, false to disable

Returns

void

Constructors

Constructor

new GridStackEngine(opts): GridStackEngine;

Defined in: gridstack-engine.ts:61

Parameters

Parameter	Type
`opts`	`GridStackEngineOptions`

Returns

Methods

_useEntireRowArea()

protected _useEntireRowArea(node, nn): boolean;

Defined in: gridstack-engine.ts:103

Parameters

Parameter	Type
`node`	`GridStackNode`
`nn`	`GridStackPosition`

Returns

boolean

addNode()

addNode(
   node, 
   triggerAddEvent, 
   after?): GridStackNode;

Defined in: gridstack-engine.ts:756

Add the given node to the grid, handling collision detection and re-packing. This is the main method for adding new widgets to the engine.

Parameters

Parameter	Type	Default value	Description
`node`	`GridStackNode`	`undefined`	the node to add to the grid
`triggerAddEvent`	`boolean`	`false`	if true, adds node to addedNodes list for event triggering
`after?`	`GridStackNode`	`undefined`	optional node to place this node after (for ordering)

Returns

the added node (or existing node if duplicate)

Example

const node = { x: 0, y: 0, w: 2, h: 1, content: 'Hello' };
const added = engine.addNode(node, true);

batchUpdate()

batchUpdate(flag, doPack): GridStackEngine;

Defined in: gridstack-engine.ts:85

Enable/disable batch mode for multiple operations to optimize performance. When enabled, layout updates are deferred until batch mode is disabled.

Parameters

Parameter	Type	Default value	Description
`flag`	`boolean`	`true`	true to enable batch mode, false to disable and apply changes
`doPack`	`boolean`	`true`	if true (default), pack/compact nodes when disabling batch mode

Returns

the engine instance for chaining

Example

// Start batch mode for multiple operations
engine.batchUpdate(true);
engine.addNode(node1);
engine.addNode(node2);
engine.batchUpdate(false); // Apply all changes at once

beginUpdate()

beginUpdate(node): GridStackEngine;

Defined in: gridstack-engine.ts:993

Parameters

Parameter	Type
`node`	`GridStackNode`

Returns

cacheLayout()

cacheLayout(
   nodes, 
   column, 
   clear): GridStackEngine;

Defined in: gridstack-engine.ts:1199

call to cache the given layout internally to the given location so we can restore back when column changes size

Parameters

Parameter	Type	Default value	Description
`nodes`	`GridStackNode`[]	`undefined`	list of nodes
`column`	`number`	`undefined`	corresponding column index to save it under
`clear`	`boolean`	`false`	if true, will force other caches to be removed (default false)

Returns

cacheOneLayout()

cacheOneLayout(n, column): GridStackEngine;

Defined in: gridstack-engine.ts:1219

call to cache the given node layout internally to the given location so we can restore back when column changes size

Parameters

Parameter	Type	Description
`n`	`GridStackNode`	-
`column`	`number`	corresponding column index to save it under

Returns

changedPosConstrain()

changedPosConstrain(node, p): boolean;

Defined in: gridstack-engine.ts:915

true if x,y or w,h are different after clamping to min/max

Parameters

Parameter	Type
`node`	`GridStackNode`
`p`	`GridStackPosition`

Returns

boolean

cleanupNode()

cleanupNode(node): GridStackEngine;

Defined in: gridstack-engine.ts:1250

called to remove all internal values but the _id

Parameters

Parameter	Type
`node`	`GridStackNode`

Returns

collide()

collide(
   skip, 
   area, 
   skip2?): GridStackNode;

Defined in: gridstack-engine.ts:182

Return the first node that intercepts/collides with the given node or area. Used for collision detection during drag and drop operations.

Parameters

Parameter	Type	Default value	Description
`skip`	`GridStackNode`	`undefined`	the node to skip in collision detection (usually the node being moved)
`area`	`GridStackNode`	`skip`	the area to check for collisions (defaults to skip node's area)
`skip2?`	`GridStackNode`	`undefined`	optional second node to skip in collision detection

Returns

the first colliding node, or undefined if no collision

Example

const colliding = engine.collide(draggedNode, {x: 2, y: 1, w: 2, h: 1});
if (colliding) {
  console.log('Would collide with:', colliding.id);
}

collideAll()

collideAll(
   skip, 
   area, 
   skip2?): GridStackNode[];

Defined in: gridstack-engine.ts:200

Return all nodes that intercept/collide with the given node or area. Similar to collide() but returns all colliding nodes instead of just the first.

Parameters

Parameter	Type	Default value	Description
`skip`	`GridStackNode`	`undefined`	the node to skip in collision detection
`area`	`GridStackNode`	`skip`	the area to check for collisions (defaults to skip node's area)
`skip2?`	`GridStackNode`	`undefined`	optional second node to skip in collision detection

Returns

array of all colliding nodes

Example

const allCollisions = engine.collideAll(draggedNode);
console.log('Colliding with', allCollisions.length, 'nodes');

compact()

compact(layout, doSort): GridStackEngine;

Defined in: gridstack-engine.ts:388

Re-layout grid items to reclaim any empty space. This optimizes the grid layout by moving items to fill gaps.

Parameters

Parameter	Type	Default value	Description
`layout`	`CompactOptions`	`'compact'`	layout algorithm to use: - 'compact' (default): find truly empty spaces, may reorder items - 'list': keep the sort order exactly the same, move items up sequentially
`doSort`	`boolean`	`true`	if true (default), sort nodes by position before compacting

Returns

the engine instance for chaining

Example

// Compact to fill empty spaces
engine.compact();

// Compact preserving item order
engine.compact('list');

directionCollideCoverage()

protected directionCollideCoverage(
   node, 
   o, 
   collides): GridStackNode;

Defined in: gridstack-engine.ts:207

does a pixel coverage collision based on where we started, returning the node that has the most coverage that is >50% mid line

Parameters

Parameter	Type
`node`	`GridStackNode`
`o`	`GridStackMoveOpts`
`collides`	`GridStackNode`[]

Returns

endUpdate()

endUpdate(): GridStackEngine;

Defined in: gridstack-engine.ts:1002

Returns

findCacheLayout()

protected findCacheLayout(n, column): number;

Defined in: gridstack-engine.ts:1233

Parameters

Parameter	Type
`n`	`GridStackNode`
`column`	`number`

Returns

number

findEmptyPosition()

findEmptyPosition(
   node, 
   nodeList, 
   column, 
   after?): boolean;

Defined in: gridstack-engine.ts:722

Find the first available empty spot for the given node dimensions. Updates the node's x,y attributes with the found position.

Parameters

Parameter	Type	Description
`node`	`GridStackNode`	the node to find a position for (w,h must be set)
`nodeList`	`GridStackNode`[]	optional list of nodes to check against (defaults to engine nodes)
`column`	`number`	optional column count (defaults to engine column count)
`after?`	`GridStackNode`	optional node to start search after (maintains order)

Returns

boolean

true if an empty position was found and node was updated

Example

const node = { w: 2, h: 1 };
if (engine.findEmptyPosition(node)) {
  console.log('Found position at:', node.x, node.y);
}

getDirtyNodes()

getDirtyNodes(verify?): GridStackNode[];

Defined in: gridstack-engine.ts:636

Returns a list of nodes that have been modified from their original values. This is used to track which nodes need DOM updates.

Parameters

Parameter	Type	Description
`verify?`	`boolean`	if true, performs additional verification by comparing current vs original positions

Returns

array of nodes that have been modified

Example

const changed = engine.getDirtyNodes();
console.log('Modified nodes:', changed.length);

// Get verified dirty nodes
const verified = engine.getDirtyNodes(true);

getRow()

getRow(): number;

Defined in: gridstack-engine.ts:989

Returns

number

isAreaEmpty()

isAreaEmpty(
   x, 
   y, 
   w, 
   h): boolean;

Defined in: gridstack-engine.ts:366

Check if the specified rectangular area is empty (no nodes occupy any part of it).

Parameters

Parameter	Type	Description
`x`	`number`	the x coordinate (column) of the area to check
`y`	`number`	the y coordinate (row) of the area to check
`w`	`number`	the width in columns of the area to check
`h`	`number`	the height in rows of the area to check

Returns

boolean

true if the area is completely empty, false if any node overlaps

Example

if (engine.isAreaEmpty(2, 1, 3, 2)) {
  console.log('Area is available for placement');
}

moveNode()

moveNode(node, o): boolean;

Defined in: gridstack-engine.ts:929

return true if the passed in node was actually moved (checks for no-op and locked)

Parameters

Parameter	Type
`node`	`GridStackNode`
`o`	`GridStackMoveOpts`

Returns

boolean

moveNodeCheck()

moveNodeCheck(node, o): boolean;

Defined in: gridstack-engine.ts:843

Check if a node can be moved to a new position, considering layout constraints. This is a safer version of moveNode() that validates the move first.

For complex cases (like maxRow constraints), it simulates the move in a clone first, then applies the changes only if they meet all specifications.

Parameters

Parameter	Type	Description
`node`	`GridStackNode`	the node to move
`o`	`GridStackMoveOpts`	move options including target position

Returns

boolean

true if the node was successfully moved

Example

const canMove = engine.moveNodeCheck(node, { x: 2, y: 1 });
if (canMove) {
  console.log('Node moved successfully');
}

nodeBoundFix()

nodeBoundFix(node, resizing?): GridStackEngine;

Defined in: gridstack-engine.ts:560

Part 2 of preparing a node to fit inside the grid - validates and fixes coordinates and dimensions. This ensures the node fits within grid boundaries and respects min/max constraints.

Parameters

Parameter	Type	Description
`node`	`GridStackNode`	the node to validate and fix
`resizing?`	`boolean`	if true, resize the node to fit; if false, move the node to fit

Returns

the engine instance for chaining

Example

// Fix a node that might be out of bounds
engine.nodeBoundFix(node, true); // Resize to fit
engine.nodeBoundFix(node, false); // Move to fit

prepareNode()

prepareNode(node, resizing?): GridStackNode;

Defined in: gridstack-engine.ts:507

Prepare and validate a node's coordinates and values for the current grid. This ensures the node has valid position, size, and properties before being added to the grid.

Parameters

Parameter	Type	Description
`node`	`GridStackNode`	the node to prepare and validate
`resizing?`	`boolean`	if true, resize the node down if it's out of bounds; if false, move it to fit

Returns

the prepared node with valid coordinates

Example

const node = { w: 3, h: 2, content: 'Hello' };
const prepared = engine.prepareNode(node);
console.log('Node prepared at:', prepared.x, prepared.y);

removeAll()

removeAll(removeDOM, triggerEvent): GridStackEngine;

Defined in: gridstack-engine.ts:816

Remove all nodes from the grid.

Parameters

Parameter	Type	Default value	Description
`removeDOM`	`boolean`	`true`	if true (default), marks all nodes for DOM removal
`triggerEvent`	`boolean`	`true`	if true (default), triggers removal events

Returns

the engine instance for chaining

Example

engine.removeAll(); // Remove all nodes

removeNode()

removeNode(
   node, 
   removeDOM, 
   triggerEvent): GridStackEngine;

Defined in: gridstack-engine.ts:790

Remove the given node from the grid.

Parameters

Parameter	Type	Default value	Description
`node`	`GridStackNode`	`undefined`	the node to remove
`removeDOM`	`boolean`	`true`	if true (default), marks node for DOM removal
`triggerEvent`	`boolean`	`false`	if true, adds node to removedNodes list for event triggering

Returns

the engine instance for chaining

Example

engine.removeNode(node, true, true);

removeNodeFromLayoutCache()

removeNodeFromLayoutCache(n): void;

Defined in: gridstack-engine.ts:1237

Parameters

Parameter	Type
`n`	`GridStackNode`

Returns

void

save()

save(
   saveElement, 
   saveCB?, 
   column?): GridStackNode[];

Defined in: gridstack-engine.ts:1018

saves a copy of the largest column layout (eg 12 even when rendering 1 column) so we don't loose orig layout, unless explicity column count to use is given. returning a list of widgets for serialization

Parameters

Parameter	Type	Default value	Description
`saveElement`	`boolean`	`true`	if true (default), the element will be saved to GridStackWidget.el field, else it will be removed.
`saveCB?`	`SaveFcn`	`undefined`	callback for each node -> widget, so application can insert additional data to be saved into the widget data structure.
`column?`	`number`	`undefined`	if provided, the grid will be saved for the given column count (IFF we have matching internal saved layout, or current layout). Note: nested grids will ALWAYS save the container w to match overall layouts (parent + child) to be consistent.

Returns

sortNodes()

sortNodes(dir): GridStackEngine;

Defined in: gridstack-engine.ts:451

Sort the nodes array from first to last, or reverse. This is called during collision/placement operations to enforce a specific order.

Parameters

Parameter	Type	Default value	Description
`dir`	`-1` \| `1`	`1`	sort direction: 1 for ascending (first to last), -1 for descending (last to first)

Returns

the engine instance for chaining

Example

engine.sortNodes();    // Sort ascending (default)
engine.sortNodes(-1);  // Sort descending

swap()

swap(a, b): boolean;

Defined in: gridstack-engine.ts:314

Attempt to swap the positions of two nodes if they meet swapping criteria. Nodes can swap if they are the same size or in the same column/row, not locked, and touching.

Parameters

Parameter	Type	Description
`a`	`GridStackNode`	first node to swap
`b`	`GridStackNode`	second node to swap

Returns

boolean

true if swap was successful, false if not possible, undefined if not applicable

Example

const swapped = engine.swap(nodeA, nodeB);
if (swapped) {
  console.log('Nodes swapped successfully');
}

willItFit()

willItFit(node): boolean;

Defined in: gridstack-engine.ts:894

return true if can fit in grid height constrain only (always true if no maxRow)

Parameters

Parameter	Type
`node`	`GridStackNode`

Returns

boolean

Properties

Property	Modifier	Type	Default value	Description	Defined in
`addedNodes`	`public`	`GridStackNode`[]	`[]`	-	gridstack-engine.ts:38
`batchMode`	`public`	`boolean`	`undefined`	-	gridstack-engine.ts:40
`column`	`public`	`number`	`undefined`	-	gridstack-engine.ts:35
`defaultColumn`	`public`	`number`	`12`	-	gridstack-engine.ts:41
`maxRow`	`public`	`number`	`undefined`	-	gridstack-engine.ts:36
`nodes`	`public`	`GridStackNode`[]	`undefined`	-	gridstack-engine.ts:37
`removedNodes`	`public`	`GridStackNode`[]	`[]`	-	gridstack-engine.ts:39
`skipCacheUpdate?`	`public`	`boolean`	`undefined`	true when grid.load() already cached the layout and can skip out of bound caching info	gridstack-engine.ts:55

Utils

Defined in: utils.ts:97

Collection of utility methods used throughout GridStack. These are general-purpose helper functions for DOM manipulation, positioning calculations, object operations, and more.

Constructors

Constructor

new Utils(): Utils;

Returns

Utils

Methods

addElStyles()

static addElStyles(el, styles): void;

Defined in: utils.ts:701

Parameters

Parameter	Type
`el`	`HTMLElement`
`styles`	{ [`prop`: `string`]: `string` \| `string`[]; }

Returns

void

appendTo()

static appendTo(el, parent): void;

Defined in: utils.ts:683

Parameters

Parameter	Type
`el`	`HTMLElement`
`parent`	`string` \| `HTMLElement`

Returns

void

area()

static area(a): number;

Defined in: utils.ts:297

Calculate the total area of a grid position.

Parameters

Parameter	Type	Description
`a`	`GridStackPosition`	position with width and height

Returns

number

the total area (width * height)

Example

const area = Utils.area({x: 0, y: 0, w: 3, h: 2}); // returns 6

areaIntercept()

static areaIntercept(a, b): number;

Defined in: utils.ts:278

Calculate the overlapping area between two grid positions.

Parameters

Parameter	Type	Description
`a`	`GridStackPosition`	first position
`b`	`GridStackPosition`	second position

Returns

number

the area of overlap (0 if no overlap)

Example

const overlap = Utils.areaIntercept(
  {x: 0, y: 0, w: 3, h: 2},
  {x: 1, y: 0, w: 3, h: 2}
); // returns 4 (2x2 overlap)

canBeRotated()

static canBeRotated(n): boolean;

Defined in: utils.ts:804

true if the item can be rotated (checking for prop, not space available)

Parameters

Parameter	Type
`n`	`GridStackNode`

Returns

boolean

clone()

static clone<T>(obj): T;

Defined in: utils.ts:646

single level clone, returning a new object with same top fields. This will share sub objects and arrays

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`obj`	`T`

Returns

T

cloneDeep()

static cloneDeep<T>(obj): T;

Defined in: utils.ts:662

Recursive clone version that returns a full copy, checking for nested objects and arrays ONLY. Note: this will use as-is any key starting with double __ (and not copy inside) some lib have circular dependencies.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`obj`	`T`

Returns

T

cloneNode()

static cloneNode(el): HTMLElement;

Defined in: utils.ts:677

deep clone the given HTML node, removing teh unique id field

Parameters

Parameter	Type
`el`	`HTMLElement`

Returns

HTMLElement

copyPos()

static copyPos(
   a, 
   b, 
   doMinMax): GridStackWidget;

Defined in: utils.ts:474

Copy position and size properties from one widget to another. Copies x, y, w, h and optionally min/max constraints.

Parameters

Parameter	Type	Default value	Description
`a`	`GridStackWidget`	`undefined`	target widget to copy to
`b`	`GridStackWidget`	`undefined`	source widget to copy from
`doMinMax`	`boolean`	`false`	if true, also copy min/max width/height constraints

Returns

GridStackWidget

the target widget (a)

Example

Utils.copyPos(widget1, widget2); // Copy position/size
Utils.copyPos(widget1, widget2, true); // Also copy constraints

createDiv()

static createDiv(classes, parent?): HTMLElement;

Defined in: utils.ts:206

Create a div element with the specified CSS classes.

Parameters

Parameter	Type	Description
`classes`	`string`[]	array of CSS class names to add
`parent?`	`HTMLElement`	optional parent element to append the div to

Returns

HTMLElement

the created div element

Example

const div = Utils.createDiv(['grid-item', 'draggable']);
const nested = Utils.createDiv(['content'], parentDiv);

defaults()

static defaults(target, ...sources): object;

Defined in: utils.ts:421

Copy unset fields from source objects to target object (shallow merge with defaults). Similar to Object.assign but only sets undefined/null fields.

Parameters

Parameter	Type	Description
`target`	`any`	the object to copy defaults into
...`sources`	`any`[]	one or more source objects to copy defaults from

Returns

object

the modified target object

Example

const config = { width: 100 };
Utils.defaults(config, { width: 200, height: 50 });
// config is now { width: 100, height: 50 }

find()

static find(nodes, id): GridStackNode;

Defined in: utils.ts:332

Find a grid node by its ID.

Parameters

Parameter	Type	Description
`nodes`	`GridStackNode`[]	array of nodes to search
`id`	`string`	the ID to search for

Returns

the node with matching ID, or undefined if not found

Example

const node = Utils.find(nodes, 'widget-1');
if (node) console.log('Found node at:', node.x, node.y);

getElement()

static getElement(els, root): HTMLElement;

Defined in: utils.ts:155

Convert a potential selector into a single HTML element. Similar to getElements() but returns only the first match.

Parameters

Parameter	Type	Default value	Description
`els`	`GridStackElement`	`undefined`	selector string or HTMLElement
`root`	`HTMLElement` \| `Document`	`document`	optional root element to search within (defaults to document)

Returns

HTMLElement

the first HTML element matching the selector, or null if not found

Example

const element = Utils.getElement('#myWidget');
const first = Utils.getElement('.grid-item');

getElements()

static getElements(els, root): HTMLElement[];

Defined in: utils.ts:112

Convert a potential selector into an actual list of HTML elements. Supports CSS selectors, element references, and special ID handling.

Parameters

Parameter	Type	Default value	Description
`els`	`GridStackElement`	`undefined`	selector string, HTMLElement, or array of elements
`root`	`HTMLElement` \| `Document`	`document`	optional root element to search within (defaults to document, useful for shadow DOM)

Returns

HTMLElement[]

array of HTML elements matching the selector

Example

const elements = Utils.getElements('.grid-item');
const byId = Utils.getElements('#myWidget');
const fromShadow = Utils.getElements('.item', shadowRoot);

getValuesFromTransformedElement()

static getValuesFromTransformedElement(parent): DragTransform;

Defined in: utils.ts:761

defines an element that is used to get the offset and scale from grid transforms returns the scale and offsets from said element

Parameters

Parameter	Type
`parent`	`HTMLElement`

Returns

DragTransform

initEvent()

static initEvent<T>(e, info): T;

Defined in: utils.ts:718

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`e`	`MouseEvent` \| `DragEvent`
`info`	{ `target?`: `EventTarget`; `type`: `string`; }
`info.target?`	`EventTarget`
`info.type`	`string`

Returns

T

isIntercepted()

static isIntercepted(a, b): boolean;

Defined in: utils.ts:244

Check if two grid positions overlap/intersect.

Parameters

Parameter	Type	Description
`a`	`GridStackPosition`	first position with x, y, w, h properties
`b`	`GridStackPosition`	second position with x, y, w, h properties

Returns

boolean

true if the positions overlap

Example

const overlaps = Utils.isIntercepted(
  {x: 0, y: 0, w: 2, h: 1},
  {x: 1, y: 0, w: 2, h: 1}
); // true - they overlap

isTouching()

static isTouching(a, b): boolean;

Defined in: utils.ts:261

Check if two grid positions are touching (edges or corners).

Parameters

Parameter	Type	Description
`a`	`GridStackPosition`	first position
`b`	`GridStackPosition`	second position

Returns

boolean

true if the positions are touching

Example

const touching = Utils.isTouching(
  {x: 0, y: 0, w: 2, h: 1},
  {x: 2, y: 0, w: 1, h: 1}
); // true - they share an edge

lazyLoad()

static lazyLoad(n): boolean;

Defined in: utils.ts:191

Check if a widget should be lazy loaded based on node or grid settings.

Parameters

Parameter	Type	Description
`n`	`GridStackNode`	the grid node to check

Returns

boolean

true if the item should be lazy loaded

Example

if (Utils.lazyLoad(node)) {
  // Set up intersection observer for lazy loading
}

parseHeight()

static parseHeight(val): HeightData;

Defined in: utils.ts:388

Parse a height value with units into numeric value and unit string. Supports px, em, rem, vh, vw, %, cm, mm units.

Parameters

Parameter	Type	Description
`val`	`numberOrString`	height value as number or string with units

Returns

HeightData

object with h (height) and unit properties

Example

Utils.parseHeight('100px');  // {h: 100, unit: 'px'}
Utils.parseHeight('2rem');   // {h: 2, unit: 'rem'}
Utils.parseHeight(50);       // {h: 50, unit: 'px'}

removeInternalAndSame()

static removeInternalAndSame(a, b): void;

Defined in: utils.ts:503

removes field from the first object if same as the second objects (like diffing) and internal '_' for saving

Parameters

Parameter	Type
`a`	`unknown`
`b`	`unknown`

Returns

void

removeInternalForSave()

static removeInternalForSave(n, removeEl): void;

Defined in: utils.ts:520

removes internal fields '_' and default values for saving

Parameters

Parameter	Type	Default value
`n`	`GridStackNode`	`undefined`
`removeEl`	`boolean`	`true`

Returns

void

removePositioningStyles()

static removePositioningStyles(el): void;

Defined in: utils.ts:553

Parameters

Parameter	Type
`el`	`HTMLElement`

Returns

void

same()

static same(a, b): boolean;

Defined in: utils.ts:450

Compare two objects for equality (shallow comparison). Checks if objects have the same fields and values at one level deep.

Parameters

Parameter	Type	Description
`a`	`unknown`	first object to compare
`b`	`unknown`	second object to compare

Returns

boolean

true if objects have the same values

Example

Utils.same({x: 1, y: 2}, {x: 1, y: 2}); // true
Utils.same({x: 1}, {x: 1, y: 2}); // false

samePos()

static samePos(a, b): boolean;

Defined in: utils.ts:489

true if a and b has same size & position

Parameters

Parameter	Type
`a`	`GridStackPosition`
`b`	`GridStackPosition`

Returns

boolean

sanitizeMinMax()

static sanitizeMinMax(node): void;

Defined in: utils.ts:494

given a node, makes sure it's min/max are valid

Parameters

Parameter	Type
`node`	`GridStackNode`

Returns

void

shouldSizeToContent()

static shouldSizeToContent(n, strict): boolean;

Defined in: utils.ts:225

Check if a widget should resize to fit its content.

Parameters

Parameter	Type	Default value	Description
`n`	`GridStackNode`	`undefined`	the grid node to check (can be undefined)
`strict`	`boolean`	`false`	if true, only returns true for explicit sizeToContent:true (not numbers)

Returns

boolean

true if the widget should resize to content

Example

if (Utils.shouldSizeToContent(node)) {
  // Trigger content-based resizing
}

simulateMouseEvent()

static simulateMouseEvent(
   e, 
   simulatedType, 
   target?): void;

Defined in: utils.ts:734

copies the MouseEvent (or convert Touch) properties and sends it as another event to the given target

Parameters

Parameter	Type
`e`	`MouseEvent` \| `Touch`
`simulatedType`	`string`
`target?`	`EventTarget`

Returns

void

sort()

static sort(nodes, dir): GridStackNode[];

Defined in: utils.ts:312

Sort an array of grid nodes by position (y first, then x).

Parameters

Parameter	Type	Default value	Description
`nodes`	`GridStackNode`[]	`undefined`	array of nodes to sort
`dir`	`-1` \| `1`	`1`	sort direction: 1 for ascending (top-left first), -1 for descending

Returns

DDBaseImplement.disabled

the sorted array (modifies original)

Example

const sorted = Utils.sort(nodes); // Sort top-left to bottom-right
const reverse = Utils.sort(nodes, -1); // Sort bottom-right to top-left

swap()

static swap(
   o, 
   a, 
   b): void;

Defined in: utils.ts:785

swap the given object 2 field values

Parameters

Parameter	Type
`o`	`unknown`
`a`	`string`
`b`	`string`

Returns

void

throttle()

static throttle(func, delay): () => void;

Defined in: utils.ts:543

delay calling the given function for given delay, preventing new calls from happening while waiting

Parameters

Parameter	Type
`func`	() => `void`
`delay`	`number`

Returns

(): void;

Returns

void

toBool()

static toBool(v): boolean;

Defined in: utils.ts:350

Convert various value types to boolean. Handles strings like 'false', 'no', '0' as false.

Parameters

Parameter	Type	Description
`v`	`unknown`	value to convert

Returns

boolean

boolean representation

Example

Utils.toBool('true');  // true
Utils.toBool('false'); // false
Utils.toBool('no');    // false
Utils.toBool('1');     // true

toNumber()

static toNumber(value): number;

Defined in: utils.ts:372

Convert a string value to a number, handling null and empty strings.

Parameters

Parameter	Type	Description
`value`	`string`	string or null value to convert

Returns

number

number value, or undefined for null/empty strings

Example

Utils.toNumber('42');  // 42
Utils.toNumber('');    // undefined
Utils.toNumber(null);  // undefined

Interfaces

GridStackOptions

Defined in: types.ts:184

Defines the options for a Grid

Properties

Property	Type	Description	Defined in
`acceptWidgets?`	`string` \| `boolean` \| (`element`) => `boolean`	Accept widgets dragged from other grids or from outside (default: `false`). Can be: - `true`: will accept HTML elements having 'grid-stack-item' as class attribute - `false`: will not accept any external widgets - string: explicit class name to accept instead of default - function: callback called before an item will be accepted when entering a grid Example `// Accept all grid items acceptWidgets: true // Accept only items with specific class acceptWidgets: 'my-draggable-item' // Custom validation function acceptWidgets: (el) => { return el.getAttribute('data-accept') === 'true'; }` See http://gridstack.github.io/gridstack.js/demo/two.html for complete example	types.ts:206
`alwaysShowResizeHandle?`	`boolean` \| `"mobile"`	possible values (default: `mobile`) - does not apply to non-resizable widgets `false` the resizing handles are only shown while hovering over a widget `true` the resizing handles are always shown 'mobile' if running on a mobile device, default to `true` (since there is no hovering per say), else `false`. See example	types.ts:213
`animate?`	`boolean`	turns animation on (default?: true)	types.ts:216
`auto?`	`boolean`	if false gridstack will not initialize existing items (default?: true)	types.ts:219
`cellHeight?`	`numberOrString`	One cell height (default: 'auto'). Can be: - an integer (px): fixed pixel height - a string (ex: '100px', '10em', '10rem'): CSS length value - 0: library will not generate styles for rows (define your own CSS) - 'auto': height calculated for square cells (width / column) and updated live on window resize - 'initial': similar to 'auto' but stays fixed size during window resizing Note: % values don't work correctly - see demo/cell-height.html Example `// Fixed 100px height cellHeight: 100 // CSS units cellHeight: '5rem' cellHeight: '100px' // Auto-sizing for square cells cellHeight: 'auto' // No CSS generation (custom styles) cellHeight: 0`	types.ts:245
`cellHeightThrottle?`	`number`	throttle time delay (in ms) used when cellHeight='auto' to improve performance vs usability (default?: 100). A value of 0 will make it instant at a cost of re-creating the CSS file at ever window resize event!	types.ts:250
`cellHeightUnit?`	`string`	(internal) unit for cellHeight (default? 'px') which is set when a string cellHeight with a unit is passed (ex: '10rem')	types.ts:253
`children?`	`GridStackWidget`[]	list of children item to create when calling load() or addGrid()	types.ts:256
`class?`	`string`	additional class on top of '.grid-stack' (which is required for our CSS) to differentiate this instance. Note: only used by addGrid(), else your element should have the needed class	types.ts:269
`column?`	`number` \| `"auto"`	number of columns (default?: 12). Note: IF you change this, CSS also have to change. See https://github.com/gridstack/gridstack.js#change-grid-columns. Note: for nested grids, it is recommended to use 'auto' which will always match the container grid-item current width (in column) to keep inside and outside items always the same. flag is NOT supported for regular non-nested grids.	types.ts:262
`columnOpts?`	`Responsive`	responsive column layout for width:column behavior	types.ts:265
`disableDrag?`	`boolean`	disallows dragging of widgets (default?: false)	types.ts:272
`disableResize?`	`boolean`	disallows resizing of widgets (default?: false).	types.ts:275
`draggable?`	`DDDragOpt`	allows to override UI draggable options. (default?: { handle?: '.grid-stack-item-content', appendTo?: 'body' })	types.ts:278
`engineClass?`	typeof `GridStackEngine`	the type of engine to create (so you can subclass) default to GridStackEngine	types.ts:284
`float?`	`boolean`	enable floating widgets (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/float.html)	types.ts:287
`handle?`	`string`	draggable handle selector (default?: '.grid-stack-item-content')	types.ts:290
`handleClass?`	`string`	draggable handle class (e.g. 'grid-stack-item-content'). If set 'handle' is ignored (default?: null)	types.ts:293
`itemClass?`	`string`	additional widget class (default?: 'grid-stack-item')	types.ts:296
`layout?`	`ColumnOptions`	re-layout mode when we're a subgrid and we are being resized. default to 'list'	types.ts:299
`lazyLoad?`	`boolean`	true when widgets are only created when they scroll into view (visible)	types.ts:302
`margin?`	`numberOrString`	gap between grid item and content (default?: 10). This will set all 4 sides and support the CSS formats below an integer (px) a string with possible units (ex: '2em', '20px', '2rem') string with space separated values (ex: '5px 10px 0 20px' for all 4 sides, or '5em 10em' for top/bottom and left/right pairs like CSS). Note: all sides must have same units (last one wins, default px)	types.ts:311
`marginBottom?`	`numberOrString`	-	types.ts:316
`marginLeft?`	`numberOrString`	-	types.ts:317
`marginRight?`	`numberOrString`	-	types.ts:315
`marginTop?`	`numberOrString`	OLD way to optionally set each side - use margin: '5px 10px 0 20px' instead. Used internally to store each side.	types.ts:314
`marginUnit?`	`string`	(internal) unit for margin (default? 'px') set when `margin` is set as string with unit (ex: 2rem')	types.ts:320
`maxRow?`	`number`	maximum rows amount. Default? is 0 which means no maximum rows	types.ts:323
`minRow?`	`number`	minimum rows amount which is handy to prevent grid from collapsing when empty. Default is `0`. When no set the `min-height` CSS attribute on the grid div (in pixels) can be used, which will round to the closest row.	types.ts:328
`nonce?`	`string`	If you are using a nonce-based Content Security Policy, pass your nonce here and GridStack will add it to the `<style>` elements it creates.	types.ts:332
`placeholderClass?`	`string`	class for placeholder (default?: 'grid-stack-placeholder')	types.ts:335
`placeholderText?`	`string`	placeholder default content (default?: '')	types.ts:338
`removable?`	`string` \| `boolean`	if true widgets could be removed by dragging outside of the grid. It could also be a selector string (ex: ".trash"), in this case widgets will be removed by dropping them there (default?: false) See example (http://gridstack.github.io/gridstack.js/demo/two.html)	types.ts:348
`removableOptions?`	`DDRemoveOpt`	allows to override UI removable options. (default?: { accept: '.grid-stack-item' })	types.ts:351
`resizable?`	`DDResizeOpt`	allows to override UI resizable options. default is { handles: 'se', autoHide: true on desktop, false on mobile }	types.ts:341
`row?`	`number`	fix grid number of rows. This is a shortcut of writing `minRow:N, maxRow:N`. (default `0` no constrain)	types.ts:354
`rtl?`	`boolean` \| `"auto"`	if true turns grid to RTL. Possible values are true, false, 'auto' (default?: 'auto') See example	types.ts:360
`sizeToContent?`	`boolean`	set to true if all grid items (by default, but item can also override) height should be based on content size instead of WidgetItem.h to avoid v-scrollbars. Note: this is still row based, not pixels, so it will use ceil(getBoundingClientRect().height / getCellHeight())	types.ts:365
`staticGrid?`	`boolean`	makes grid static (default?: false). If `true` widgets are not movable/resizable. You don't even need draggable/resizable. A CSS class 'grid-stack-static' is also added to the element.	types.ts:372
~~`styleInHead?`~~	`boolean`	Deprecated Not used anymore, styles are now implemented with local CSS variables	types.ts:377
`subGridDynamic?`	`boolean`	enable/disable the creation of sub-grids on the fly by dragging items completely over others (nest) vs partially (push). Forces `DDDragOpt.pause=true` to accomplish that.	types.ts:384
`subGridOpts?`	`GridStackOptions`	list of differences in options for automatically created sub-grids under us (inside our grid-items)	types.ts:380

`abstract` DDBaseImplement

Defined in: dd-base-impl.ts:17

Abstract base class for all drag & drop implementations. Provides common functionality for event handling, enable/disable state, and lifecycle management used by draggable, droppable, and resizable implementations.

Accessors

disabled

Get Signature

get disabled(): boolean;

Defined in: dd-base-impl.ts:22

Returns the current disabled state. Note: Use enable()/disable() methods to change state as other operations need to happen.

Returns

boolean

Constructors

Constructor

new DDBaseImplement(): DDBaseImplement;

Returns

DDBaseImplement

Methods

destroy()

destroy(): void;

Defined in: dd-base-impl.ts:70

Destroy this drag & drop implementation and clean up resources. Removes all event handlers and clears internal state.

Returns

void

disable()

disable(): void;

Defined in: dd-base-impl.ts:62

Disable this drag & drop implementation. Subclasses should override to perform additional cleanup.

Returns

void

enable()

enable(): void;

Defined in: dd-base-impl.ts:54

Enable this drag & drop implementation. Subclasses should override to perform additional setup.

Returns

void

off()

off(event): void;

Defined in: dd-base-impl.ts:46

Unregister an event callback for the specified event.

Parameters

Parameter	Type	Description
`event`	`string`	Event name to stop listening for

Returns

void

on()

on(event, callback): void;

Defined in: dd-base-impl.ts:37

Parameters

Parameter	Type	Description
`event`	`string`	Event name to listen for
`callback`	`EventCallback`	Function to call when event occurs

Returns

void

triggerEvent()

triggerEvent(eventName, event): boolean | void;

Defined in: dd-base-impl.ts:81

Trigger a registered event callback if one exists and the implementation is enabled.

Parameters

Parameter	Type	Description
`eventName`	`string`	Name of the event to trigger
`event`	`Event`	DOM event object to pass to the callback

Returns

boolean | void

Result from the callback function, if any

DDDraggable

Defined in: dd-draggable.ts:34

Interface for HTML elements extended with drag & drop options. Used to associate DD configuration with DOM elements.

Extends

DDBaseImplement

Implements

HTMLElementExtendOpt<DDDragOpt>

Accessors

disabled

Get Signature

get disabled(): boolean;

Defined in: dd-base-impl.ts:22

Returns the current disabled state. Note: Use enable()/disable() methods to change state as other operations need to happen.

Returns

boolean

Inherited from

Constructors

Constructor

new DDDraggable(el, option): DDDraggable;

Defined in: dd-draggable.ts:65

Parameters

Parameter	Type
`el`	`GridItemHTMLElement`
`option`	`DDDragOpt`

Returns

DDDraggable

Overrides

DDBaseImplement.constructor

Methods

destroy()

destroy(): void;

Defined in: dd-draggable.ts:118

Destroy this drag & drop implementation and clean up resources. Removes all event handlers and clears internal state.

Returns

void

Overrides

DDBaseImplement.destroy

disable()

disable(forDestroy): void;

Defined in: dd-draggable.ts:105

Disable this drag & drop implementation. Subclasses should override to perform additional cleanup.

Parameters

Parameter	Type	Default value
`forDestroy`	`boolean`	`false`

Returns

void

Overrides

DDBaseImplement.disable

enable()

enable(): void;

Defined in: dd-draggable.ts:91

Enable this drag & drop implementation. Subclasses should override to perform additional setup.

Returns

void

Overrides

DDBaseImplement.enable

off()

off(event): void;

Defined in: dd-draggable.ts:87

Unregister an event callback for the specified event.

Parameters

Parameter	Type	Description
`event`	`DDDragEvent`	Event name to stop listening for

Returns

void

Overrides

DDBaseImplement.off

on()

on(event, callback): void;

Defined in: dd-draggable.ts:83

Parameters

Parameter	Type	Description
`event`	`DDDragEvent`	Event name to listen for
`callback`	(`event`) => `void`	Function to call when event occurs

Returns

void

Overrides

DDBaseImplement.on

triggerEvent()

triggerEvent(eventName, event): boolean | void;

Defined in: dd-base-impl.ts:81

Trigger a registered event callback if one exists and the implementation is enabled.

Parameters

Parameter	Type	Description
`eventName`	`string`	Name of the event to trigger
`event`	`Event`	DOM event object to pass to the callback

Returns

boolean | void

Result from the callback function, if any

Inherited from

DDBaseImplement.triggerEvent

updateOption()

updateOption(opts): DDDraggable;

Defined in: dd-draggable.ts:129

Method to update the options and return the DD implementation

Parameters

Parameter	Type
`opts`	`DDDragOpt`

Returns

DDDraggable

Implementation of

HTMLElementExtendOpt.updateOption

Properties

Property	Modifier	Type	Default value	Description	Defined in
`el`	`public`	`GridItemHTMLElement`	`undefined`	The HTML element being extended	dd-draggable.ts:65
`helper`	`public`	`HTMLElement`	`undefined`	-	dd-draggable.ts:35
`option`	`public`	`DDDragOpt`	`{}`	The drag & drop options/configuration	dd-draggable.ts:65

DDDroppable

Defined in: dd-droppable.ts:23

Interface for HTML elements extended with drag & drop options. Used to associate DD configuration with DOM elements.

Extends

DDBaseImplement

Implements

HTMLElementExtendOpt<DDDroppableOpt>

Accessors

disabled

Get Signature

get disabled(): boolean;

Defined in: dd-base-impl.ts:22

Returns the current disabled state. Note: Use enable()/disable() methods to change state as other operations need to happen.

Returns

boolean

Inherited from

DDBaseImplement.disabled

Constructors

Constructor

new DDDroppable(el, option): DDDroppable;

Defined in: dd-droppable.ts:27

Parameters

Parameter	Type
`el`	`HTMLElement`
`option`	`DDDroppableOpt`

Returns

DDDroppable

Overrides

DDBaseImplement.constructor

Methods

destroy()

destroy(): void;

Defined in: dd-droppable.ts:70

Destroy this drag & drop implementation and clean up resources. Removes all event handlers and clears internal state.

Returns

void

Overrides

DDBaseImplement.destroy

disable()

disable(forDestroy): void;

Defined in: dd-droppable.ts:57

Disable this drag & drop implementation. Subclasses should override to perform additional cleanup.

Parameters

Parameter	Type	Default value
`forDestroy`	`boolean`	`false`

Returns

void

Overrides

DDBaseImplement.disable

drop()

drop(e): void;

Defined in: dd-droppable.ts:143

item is being dropped on us - called by the drag mouseup handler - this calls the client drop event

Parameters

Parameter	Type
`e`	`MouseEvent`

Returns

void

enable()

enable(): void;

Defined in: dd-droppable.ts:44

Enable this drag & drop implementation. Subclasses should override to perform additional setup.

Returns

void

Overrides

DDBaseImplement.enable

off()

off(event): void;

Defined in: dd-droppable.ts:40

Unregister an event callback for the specified event.

Parameters

Parameter	Type	Description
`event`	`"drop"` \| `"dropover"` \| `"dropout"`	Event name to stop listening for

Returns

void

Overrides

DDBaseImplement.off

on()

on(event, callback): void;

Defined in: dd-droppable.ts:36

Parameters

Parameter	Type	Description
`event`	`"drop"` \| `"dropover"` \| `"dropout"`	Event name to listen for
`callback`	(`event`) => `void`	Function to call when event occurs

Returns

void

Overrides

DDBaseImplement.on

triggerEvent()

triggerEvent(eventName, event): boolean | void;

Defined in: dd-base-impl.ts:81

Trigger a registered event callback if one exists and the implementation is enabled.

Parameters

Parameter	Type	Description
`eventName`	`string`	Name of the event to trigger
`event`	`Event`	DOM event object to pass to the callback

Returns

boolean | void

Result from the callback function, if any

Inherited from

DDBaseImplement.triggerEvent

updateOption()

updateOption(opts): DDDroppable;

Defined in: dd-droppable.ts:77

Method to update the options and return the DD implementation

Parameters

Parameter	Type
`opts`	`DDDroppableOpt`

Returns

DDDroppable

Implementation of

HTMLElementExtendOpt.updateOption

Properties

Property	Modifier	Type	Default value	Description	Defined in
`accept`	`public`	(`el`) => `boolean`	`undefined`	-	dd-droppable.ts:25
`el`	`public`	`HTMLElement`	`undefined`	The HTML element being extended	dd-droppable.ts:27
`option`	`public`	`DDDroppableOpt`	`{}`	The drag & drop options/configuration	dd-droppable.ts:27

DDElement

Defined in: dd-element.ts:15

Constructors

Constructor

new DDElement(el): DDElement;

Defined in: dd-element.ts:26

Parameters

Parameter	Type
`el`	`DDElementHost`

Returns

Methods

cleanDraggable()

cleanDraggable(): DDElement;

Defined in: dd-element.ts:59

Returns

cleanDroppable()

cleanDroppable(): DDElement;

Defined in: dd-element.ts:93

Returns

cleanResizable()

cleanResizable(): DDElement;

Defined in: dd-element.ts:76

Returns

init()

static init(el): DDElement;

Defined in: dd-element.ts:17

Parameters

Parameter	Type
`el`	`DDElementHost`

Returns

off()

off(eventName): DDElement;

Defined in: dd-element.ts:39

Parameters

Parameter	Type
`eventName`	`string`

Returns

on()

on(eventName, callback): DDElement;

Defined in: dd-element.ts:28

Parameters

Parameter	Type
`eventName`	`string`
`callback`	(`event`) => `void`

Returns

setupDraggable()

setupDraggable(opts): DDElement;

Defined in: dd-element.ts:50

Parameters

Parameter	Type
`opts`	`DDDragOpt`

Returns

setupDroppable()

setupDroppable(opts): DDElement;

Defined in: dd-element.ts:84

Parameters

Parameter	Type
`opts`	`DDDroppableOpt`

Returns

setupResizable()

setupResizable(opts): DDElement;

Defined in: dd-element.ts:67

Parameters

Parameter	Type
`opts`	`DDResizableOpt`

Returns

Properties

Property	Modifier	Type	Defined in
`ddDraggable?`	`public`	`DDDraggable`	dd-element.ts:22
`ddDroppable?`	`public`	`DDDroppable`	dd-element.ts:23
`ddResizable?`	`public`	`DDResizable`	dd-element.ts:24
`el`	`public`	`DDElementHost`	dd-element.ts:26

DDGridStack

Defined in: dd-gridstack.ts:57

HTML Native Mouse and Touch Events Drag and Drop functionality.

This class provides the main drag & drop implementation for GridStack, handling resizing, dragging, and dropping of grid items using native HTML5 events. It manages the interaction between different DD components and the grid system.

Constructors

Constructor

new DDGridStack(): DDGridStack;

Returns

Methods

draggable()

draggable(
   el, 
   opts, 
   key?, 
   value?): DDGridStack;

Defined in: dd-gridstack.ts:120

Enable/disable/configure dragging for grid elements.

Parameters

Parameter	Type	Description
`el`	`GridItemHTMLElement`	Grid item element(s) to configure
`opts`	`any`	Drag options or command ('enable', 'disable', 'destroy', 'option', or config object)
`key?`	`DDKey`	Option key when using 'option' command
`value?`	`DDValue`	Option value when using 'option' command

Returns

this instance for chaining

Example

dd.draggable(element, 'enable');  // Enable dragging
dd.draggable(element, {handle: '.drag-handle'});  // Configure drag handle

dragIn()

dragIn(el, opts): DDGridStack;

Defined in: dd-gridstack.ts:144

Parameters

Parameter	Type
`el`	`GridStackElement`
`opts`	`DDDragOpt`

Returns

droppable()

droppable(
   el, 
   opts, 
   key?, 
   value?): DDGridStack;

Defined in: dd-gridstack.ts:149

Parameters

Parameter	Type
`el`	`GridItemHTMLElement`
`opts`	`any`
`key?`	`DDKey`
`value?`	`DDValue`

Returns

isDraggable()

isDraggable(el): boolean;

Defined in: dd-gridstack.ts:174

true if element is draggable

Parameters

Parameter	Type
`el`	`DDElementHost`

Returns

boolean

isDroppable()

isDroppable(el): boolean;

Defined in: dd-gridstack.ts:169

true if element is droppable

Parameters

Parameter	Type
`el`	`DDElementHost`

Returns

boolean

isResizable()

isResizable(el): boolean;

Defined in: dd-gridstack.ts:179

true if element is draggable

Parameters

Parameter	Type
`el`	`DDElementHost`

Returns

boolean

off()

off(el, name): DDGridStack;

Defined in: dd-gridstack.ts:195

Parameters

Parameter	Type
`el`	`GridItemHTMLElement`
`name`	`string`

Returns

on()

on(
   el, 
   name, 
   callback): DDGridStack;

Defined in: dd-gridstack.ts:183

Parameters

Parameter	Type
`el`	`GridItemHTMLElement`
`name`	`string`
`callback`	`DDCallback`

Returns

resizable()

resizable(
   el, 
   opts, 
   key?, 
   value?): DDGridStack;

Defined in: dd-gridstack.ts:72

Enable/disable/configure resizing for grid elements.

Parameters

Parameter	Type	Description
`el`	`GridItemHTMLElement`	Grid item element(s) to configure
`opts`	`any`	Resize options or command ('enable', 'disable', 'destroy', 'option', or config object)
`key?`	`DDKey`	Option key when using 'option' command
`value?`	`DDValue`	Option value when using 'option' command

Returns