gridstack - v12.3.3
    Preparing search index...

    Class Utils

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

    Index

    Constructors

    constructor

    Methods

    addElStyles appendTo area areaIntercept canBeRotated clone cloneDeep cloneNode copyPos createDiv defaults find getElement getElements getValuesFromTransformedElement initEvent isIntercepted isTouching lazyLoad parseHeight removeInternalAndSame removeInternalForSave removePositioningStyles same samePos sanitizeMinMax shouldSizeToContent simulateMouseEvent sort swap throttle toBool toNumber

    Constructors

    Methods

    • Parameters

      • el: HTMLElement
      • styles: { [prop: string]: string | string[] }

      Returns void

    • Parameters

      • el: HTMLElement
      • parent: string | HTMLElement

      Returns void

    • Calculate the total area of a grid position.

      Parameters

      Returns number

      the total area (width * height)

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

    • Calculate the overlapping area between two grid positions.

      Parameters

      Returns number

      the area of overlap (0 if no overlap)

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

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

      Type Parameters

      • T

      Parameters

      • obj: T

      Returns T

    • 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

      • T

      Parameters

      • obj: T

      Returns T

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

      Parameters

      • el: HTMLElement

      Returns HTMLElement

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

      Parameters

      • a: GridStackWidget

        target widget to copy to

      • b: GridStackWidget

        source widget to copy from

      • doMinMax: boolean = false

        if true, also copy min/max width/height constraints

      Returns GridStackWidget

      the target widget (a)

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

    • Create a div element with the specified CSS classes.

      Parameters

      • classes: string[]

        array of CSS class names to add

      • Optionalparent: HTMLElement

        optional parent element to append the div to

      Returns HTMLElement

      the created div element

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

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

      Parameters

      • target: any

        the object to copy defaults into

      • ...sources: any[]

        one or more source objects to copy defaults from

      Returns {}

      the modified target object

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

    • Find a grid node by its ID.

      Parameters

      • nodes: GridStackNode[]

        array of nodes to search

      • id: string

        the ID to search for

      Returns GridStackNode

      the node with matching ID, or undefined if not found

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

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

      Parameters

      • els: GridStackElement

        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

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

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

      Parameters

      • els: GridStackElement

        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

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

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

      Parameters

      • parent: HTMLElement

      Returns DragTransform

    • Type Parameters

      • T

      Parameters

      • e: MouseEvent | DragEvent
      • info: { target?: EventTarget; type: string }

      Returns T

    • Check if two grid positions overlap/intersect.

      Parameters

      Returns boolean

      true if the positions overlap

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

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

      Parameters

      Returns boolean

      true if the positions are touching

      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

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

      Parameters

      Returns boolean

      true if the item should be lazy loaded

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

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

      Parameters

      Returns HeightData

      object with h (height) and unit properties

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

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

      Parameters

      • a: unknown
      • b: unknown

      Returns void

    • removes internal fields '_' and default values for saving

      Parameters

      Returns void

    • Parameters

      • el: HTMLElement

      Returns void

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

      Parameters

      • a: unknown

        first object to compare

      • b: unknown

        second object to compare

      Returns boolean

      true if objects have the same values

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

    • Check if a widget should resize to fit its content.

      Parameters

      • n: GridStackNode

        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

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

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

      Parameters

      • e: MouseEvent | Touch
      • simulatedType: string
      • Optionaltarget: EventTarget

      Returns void

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

      Parameters

      • nodes: GridStackNode[]

        array of nodes to sort

      • dir: -1 | 1 = 1

        sort direction: 1 for ascending (top-left first), -1 for descending

      Returns GridStackNode[]

      the sorted array (modifies original)

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

    • swap the given object 2 field values

      Parameters

      • o: unknown
      • a: string
      • b: string

      Returns void

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

      Parameters

      • func: () => void
      • delay: number

      Returns () => void

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

      Parameters

      • v: unknown

        value to convert

      Returns boolean

      boolean representation

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

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

      Parameters

      • value: string

        string or null value to convert

      Returns number

      number value, or undefined for null/empty strings

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

    Settings

    Member Visibility

    On This Page

    Constructors
    Methods