gridstack
    Preparing search index...

    Class GridStackEngine

    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.

    Index

    Accessors

    float

    Constructors

    constructor

    Methods

    _useEntireRowArea addNode batchUpdate beginUpdate cacheLayout cacheOneLayout changedPosConstrain cleanupNode collide collideAll compact directionCollideCoverage endUpdate findCacheLayout findEmptyPosition getDirtyNodes getRow isAreaEmpty moveNode moveNodeCheck nodeBoundFix prepareNode removeAll removeNode removeNodeFromLayoutCache save sortNodes swap willItFit

    Properties

    addedNodes batchMode column defaultColumn maxRow nodes removedNodes skipCacheUpdate?

    Accessors

    • get float(): boolean

      Get the current floating mode setting.

      Returns boolean

      true if floating is enabled, false otherwise

      const isFloating = engine.float;
      console.log('Floating enabled:', isFloating);
    • set float(val: boolean): void

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

      Parameters

      • val: boolean

        true to enable floating, false to disable

      Returns void

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

    Constructors

    Methods

    Protected_useEntireRowArea

    • 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

      • node: GridStackNode

        the node to add to the grid

      • triggerAddEvent: boolean = false

        if true, adds node to addedNodes list for event triggering

      • Optionalafter: GridStackNode

        optional node to place this node after (for ordering)

      Returns GridStackNode

      the added node (or existing node if duplicate)

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

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

      Parameters

      • 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 GridStackEngine

      the engine instance for chaining

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

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

      Parameters

      • nodes: GridStackNode[]

        list of nodes

      • column: number

        corresponding column index to save it under

      • clear: boolean = false

        if true, will force other caches to be removed (default false)

      Returns GridStackEngine

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

      Parameters

      • skip: GridStackNode

        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)

      • Optionalskip2: GridStackNode

        optional second node to skip in collision detection

      Returns GridStackNode

      the first colliding node, or undefined if no collision

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

    • 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

      • skip: GridStackNode

        the node to skip in collision detection

      • area: GridStackNode = skip

        the area to check for collisions (defaults to skip node's area)

      • Optionalskip2: GridStackNode

        optional second node to skip in collision detection

      Returns GridStackNode[]

      array of all colliding nodes

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

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

      Parameters

      • 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 GridStackEngine

      the engine instance for chaining

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

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

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

      Parameters

      • 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)

      • Optionalafter: GridStackNode

        optional node to start search after (maintains order)

      Returns boolean

      true if an empty position was found and node was updated

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

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

      Parameters

      • Optionalverify: boolean

        if true, performs additional verification by comparing current vs original positions

      Returns GridStackNode[]

      array of nodes that have been modified

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

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

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

      Parameters

      • 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

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

    • 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

      Returns boolean

      true if the node was successfully moved

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

    • 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

      • node: GridStackNode

        the node to validate and fix

      • Optionalresizing: boolean

        if true, resize the node to fit; if false, move the node to fit

      Returns GridStackEngine

      the engine instance for chaining

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

    • 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

      • node: GridStackNode

        the node to prepare and validate

      • Optionalresizing: boolean

        if true, resize the node down if it's out of bounds; if false, move it to fit

      Returns GridStackNode

      the prepared node with valid coordinates

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

    • Remove all nodes from the grid.

      Parameters

      • removeDOM: boolean = true

        if true (default), marks all nodes for DOM removal

      • triggerEvent: boolean = true

        if true (default), triggers removal events

      Returns GridStackEngine

      the engine instance for chaining

      engine.removeAll(); // Remove all nodes

    • Remove the given node from the grid.

      Parameters

      • node: GridStackNode

        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 GridStackEngine

      the engine instance for chaining

      engine.removeNode(node, true, true);

    • saves a copy of the largest column layout (eg 12 even when rendering oneColumnMode) so we don't loose orig layout, returning a list of widgets for serialization

      Parameters

      • saveElement: boolean = true
      • OptionalsaveCB: SaveFcn

      Returns GridStackNode[]

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

      Parameters

      • dir: -1 | 1 = 1

        sort direction: 1 for ascending (first to last), -1 for descending (last to first)

      Returns GridStackEngine

      the engine instance for chaining

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

    • 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

      Returns boolean

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

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

    Properties

    addedNodes: GridStackNode[] = []
    batchMode: boolean
    column: number
    defaultColumn: number = 12
    maxRow: number
    nodes: GridStackNode[]
    removedNodes: GridStackNode[] = []
    skipCacheUpdate?: boolean

    true when grid.load() already cached the layout and can skip out of bound caching info

    Settings

    Member Visibility

    On This Page

    Accessors
    Constructors
    Methods
    Properties