interact.js

API Reference

interact(element)

The methods of this variable can be used to set elements as interactables and also to change various default settings.

Calling it as a function and passing an element or a valid CSS selector string returns an Interactable object which has various methods to configure it.

Parameters

  1. element Element string The HTML or SVG Element to interact with or CSS selector

Returns: object An Interactable

Usage

interact(document.getElementById('draggable')).draggable(true);

var rectables = interact('rect');
rectables
    .gesturable(true)
    .on('gesturemove', function (event) {
        // something cool...
    })
    .autoScroll(true);

Interactable.draggable([options])

Gets or sets whether drag actions can be performed on the Interactable

Returns: boolean Indicates if this can be the target of drag events

var isDraggable = interact('ul li').draggable();

or

Parameters

  1. options boolean object true/false or An object with event listeners to be fired on drag events (object makes the Interactable draggable)

Returns: object This Interactable

interact(element).draggable({
    onstart: function (event) {},
    onmove : function (event) {},
    onend  : function (event) {},

    // the axis in which the first movement must be
    // for the drag sequence to start
    // 'xy' by default - any direction
    axis: 'x' || 'y' || 'xy'
});

Interactable.dropzone([options])

Returns or sets whether elements can be dropped onto this Interactable to trigger drop events

Dropzones can recieve the following events:

  • dragactivate and dragdeactivate when an acceptable drag starts and ends
  • dragenter and dragleave when a draggable enters and leaves the dropzone
  • drop when a draggable is dropped into this dropzone
  • Use the accept option to allow only elements that match the given CSS selector or element.

    Use the overlap option to set how drops are checked for. The allowed values are:

  • 'pointer', the pointer must be over the dropzone (default)
  • 'center', the draggable element's center must be over the dropzone
  • a number from 0-1 which is the (intersetion area) / (draggable area).
  • e.g. `0.5` for drop to happen when half of the area of the draggable is over the dropzone

    Parameters

    1. options boolean object null The new value to be set.
    interact('.drop').dropzone({
      accept: '.can-drop' || document.getElementById('single-drop'),
      overlap: 'pointer' || 'center' || zeroToOne
    }

    Returns: boolean object The current setting or this Interactable

    Interactable.dropCheck(event)

    The default function to determine if a dragend event occured over this Interactable's element. Can be overridden using Interactable.dropChecker.

    Parameters

    1. event MouseEvent TouchEvent The event that ends a drag

    Returns: boolean whether the pointer was over this Interactable

    Interactable.dropChecker([checker])

    Gets or sets the function used to check if a dragged element is over this Interactable. See Interactable.dropCheck.

    Parameters

    1. checker function

    The checker is a function which takes a mouseUp/touchEnd event as a parameter and returns true or false to indicate if the the current draggable can be dropped into this Interactable

    Returns: Function Interactable The checker function or this Interactable

    Interactable.accept([newValue])

    Gets or sets the Element or CSS selector match that this Interactable accepts if it is a dropzone.

    Parameters

    1. newValue Element string null

    If it is an Element, then only that element can be dropped into this dropzone. If it is a string, the element being dragged must match it as a selector. If it is null, the accept options is cleared - it accepts any element.

    Returns: string Element null Interactable The current accept option if given undefined or this Interactable

    Interactable.resizable([options])

    Gets or sets whether resize actions can be performed on the Interactable

    Returns: boolean Indicates if this can be the target of resize elements

    var isResizeable = interact('input[type=text]').resizable();

    or

    Parameters

    1. options boolean object true/false or An object with event listeners to be fired on resize events (object makes the Interactable resizable)

    Returns: object This Interactable

    interact(element).resizable({
        onstart: function (event) {},
        onmove : function (event) {},
        onend  : function (event) {},
    
        axis   : 'x' || 'y' || 'xy' // default is 'xy'
    });

    Interactable.squareResize([newValue])

    Gets or sets whether resizing is forced 1:1 aspect

    Returns: boolean Current setting

    or

    Parameters

    1. newValue boolean

    Returns: object this Interactable

    Interactable.gesturable([options])

    Gets or sets whether multitouch gestures can be performed on the Interactable's element

    Returns: boolean Indicates if this can be the target of gesture events

    var isGestureable = interact(element).gesturable();

    or

    Parameters

    1. options boolean object true/false or An object with event listeners to be fired on gesture events (makes the Interactable gesturable)

    Returns: object this Interactable

    interact(element).gesturable({
        onmove: function (event) {}
    });

    Interactable.autoScroll([options])

    Returns or sets whether or not any actions near the edges of the window/container trigger autoScroll for this Interactable

    Returns: boolean object

    false if autoScroll is disabled; object with autoScroll properties if autoScroll is enabled

    or

    Parameters

    1. options object boolean null

    options can be:

  • an object with margin, distance and interval properties,
  • true or false to enable or disable autoScroll or
  • null to use default settings
  • Returns: Interactable this Interactable

    Interactable.snap([options])

    Returns or sets if and how action coordinates are snapped. By default, snapping is relative to the pointer coordinates. You can change this by setting the elementOrigin.

    Returns: boolean object false if snap is disabled; object with snap properties if snap is enabled

    or

    Parameters

    1. options object boolean null

    Returns: Interactable this Interactable

    Usage

    interact('.handle').snap({
        mode        : 'grid',                // event coords should snap to the corners of a grid
        range       : Infinity,              // the effective distance of snap ponts
        grid        : { x: 100, y: 100 },    // the x and y spacing of the grid points
        gridOffset  : { x:   0, y:   0 },    // the offset of the grid points
    });
    
    interact('.handle').snap({
        mode        : 'anchor',              // snap to specified points
        anchors     : [
            { x: 100, y: 100, range: 25 },   // a point with x, y and a specific range
            { x: 200, y: 200 }               // a point with x and y. it uses the default range
        ]
    });
    
    interact(document.querySelector('#thing')).snap({
        mode : 'path',
        paths: [
            {            // snap to points on these x and y axes
                x: 100,
                y: 100,
                range: 25
            },
            // give this function the x and y page coords and snap to the object returned
            function (x, y) {
                return {
                    x: x,
                    y: (75 + 50 * Math.sin(x * 0.04)),
                    range: 40
                };
            }]
    })
    
    interact(element).snap({
        // do not snap during normal movement.
        // Instead, trigger only one snapped move event
        // immediately before the end event.
        endOnly: true,
    
        // https://github.com/taye/interact.js/pull/72#issue-41813493
        elementOrigin: { x: 0, y: 0 }
    });

    Interactable.inertia([options])

    Returns or sets if and how events continue to run after the pointer is released

    Returns: boolean object false if inertia is disabled; object with inertia properties if inertia is enabled

    or

    Parameters

    1. options object boolean null

    Returns: Interactable this Interactable

    Usage

    // enable and use default settings
    interact(element).inertia(true);
    
    // enable and use custom settings
    interact(element).inertia({
        // value greater than 0
        // high values slow the object down more quickly
        resistance     : 16,
    
        // the minimum launch speed (pixels per second) that results in inertiastart
        minSpeed       : 200,
    
        // inertia will stop when the object slows down to this speed
        endSpeed       : 20,
    
        // boolean; should the jump when resuming from inertia be ignored in event.dx/dy
        zeroResumeDelta: false,
    
        // if snap/restrict are set to be endOnly and inertia is enabled, releasing
        // the pointer without triggering inertia will animate from the release
        // point to the snaped/restricted point in the given amount of time (ms)
        smoothEndDuration: 300,
    
        // an array of action types that can have inertia (no gesture)
        actions        : ['drag', 'resize']
    });
    
    // reset custom settings and use all defaults
    interact(element).inertia(null);

    Interactable.actionChecker([checker])

    Gets or sets the function used to check action to be performed on pointerDown

    Parameters

    1. checker function null A function which takes a pointer event, defaultAction string and an interactable as parameters and returns 'drag' 'resize[axes]' or 'gesture' or null.

    Returns: Function Interactable The checker function or this Interactable

    Interactable.getRect([element])

    The default function to get an Interactables bounding rect. Can be overridden using Interactable.rectChecker.

    Parameters

    1. element Element The element to measure. Meant to be used for selector Interactables which don't have a specific element.

    Returns: object The object's bounding rectangle.

    1. {
      1. top : 0,
      2. left : 0,
      3. bottom: 0,
      4. right : 0,
      5. width : 0,
      6. height: 0
    2. }

    Interactable.rectChecker([checker])

    Returns or sets the function used to calculate the interactable's element's rectangle

    Parameters

    1. checker function A function which returns this Interactable's bounding rectangle. See Interactable.getRect

    Returns: function object The checker function or this Interactable

    Interactable.styleCursor([newValue])

    Returns or sets whether the action that would be performed when the mouse on the element are checked on mousemove so that the cursor may be styled appropriately

    Parameters

    1. newValue boolean

    Returns: boolean Interactable The current setting or this Interactable

    Interactable.preventDefault([newValue])

    Returns or sets whether to prevent the browser's default behaviour in response to pointer events. Can be set to

  • true to always prevent
  • false to never prevent
  • 'auto' to allow interact.js to try to guess what would be best
  • null to set to the default ('auto')
  • Parameters

    1. newValue boolean string null true, false or 'auto'

    Returns: boolean string Interactable The current setting or this Interactable

    Interactable.origin(…)

    Gets or sets the origin of the Interactable's element. The x and y of the origin will be subtracted from action event coordinates.

    Parameters

    1. origin object An object with x and y properties which are numbers

    OR

    Parameters

    1. origin Element An HTML or SVG Element whose rect will be used

    Returns: object The current origin or this Interactable

    Interactable.deltaSource([source])

    Returns or sets the mouse coordinate types used to calculate the movement of the pointer.

    Parameters

    1. source string Use 'client' if you will be scrolling while interacting; Use 'page' if you want autoScroll to work

    Returns: string object The current deltaSource or this Interactable

    Interactable.restrict([newValue])

    Returns or sets the rectangles within which actions on this interactable (after snap calculations) are restricted. By default, restricting is relative to the pointer coordinates. You can change this by setting the elementRect.

    Parameters

    1. newValue object an object with keys drag, resize, and/or gesture and rects or Elements as values

    Returns: object The current restrictions object or this Interactable

    interact(element).restrict({
        // the rect will be `interact.getElementRect(element.parentNode)`
        drag: element.parentNode,
    
        // x and y are relative to the the interactable's origin
        resize: { x: 100, y: 100, width: 200, height: 200 }
    })
    
    interact('.draggable').restrict({
        // the rect will be the selected element's parent
        drag: 'parent',
    
        // do not restrict during normal movement.
        // Instead, trigger only one restricted move event
        // immediately before the end event.
        endOnly: true,
    
        // https://github.com/taye/interact.js/pull/72#issue-41813493
        elementRect: { top: 0, left: 0, bottom: 1, right: 1 }
    });

    Interactable.context()

    Get's the selector context Node of the Interactable. The default is window.document.

    Returns: Node The context Node of this Interactable

    Interactable.ignoreFrom([newValue])

    If the target of the mousedown, pointerdown or touchstart event or any of it's parents match the given CSS selector or Element, no drag/resize/gesture is started.

    Parameters

    1. newValue string Element null a CSS selector string, an Element or null to not ignore any elements

    Returns: string Element object The current ignoreFrom value or this Interactable

    interact(element, { ignoreFrom: document.getElementById('no-action') });
    // or
    interact(element).ignoreFrom('input, textarea, a');

    Interactable.allowFrom([newValue])

    A drag/resize/gesture is started only If the target of the mousedown, pointerdown or touchstart event or any of it's parents match the given CSS selector or Element.

    Parameters

    1. newValue string Element null a CSS selector string, an Element or null to allow from any element

    Returns: string Element object The current allowFrom value or this Interactable

    interact(element, { allowFrom: document.getElementById('drag-handle') });
    // or
    interact(element).allowFrom('.handle');

    Interactable.validateSetting(context, option, value)

    Parameters

    1. context string eg. 'snap', 'autoScroll'
    2. option string The name of the value being set
    3. value any type The value being validated

    Returns: typeof value A valid value for the give context-option pair

  • null if defaultOptions[context][value] is undefined
  • value if it is the same type as defaultOptions[context][value],
  • this.options[context][value] if it is the same type as defaultOptions[context][value],
  • or defaultOptions[context][value]
  • Interactable.element()

    If this is not a selector Interactable, it returns the element this interactable represents

    Returns: Element HTML / SVG Element

    Interactable.fire(iEvent)

    Calls listeners for the given InteractEvent type bound globablly and directly to this Interactable

    Parameters

    1. iEvent InteractEvent The InteractEvent object to be fired on this Interactable

    Returns: Interactable this Interactable

    Interactable.on(eventType, listener, [useCapture])

    Binds a listener for an InteractEvent or DOM event.

    Parameters

    1. eventType string The type of event to listen for
    2. listener function The function to be called on that event
    3. useCapture boolean useCapture flag for addEventListener

    Returns: object This Interactable

    Interactable.off(eventType, listener, [useCapture])

    Removes an InteractEvent or DOM event listener

    Parameters

    1. eventType string The type of event that was listened for
    2. listener function The listener function to be removed
    3. useCapture boolean useCapture flag for removeEventListener

    Returns: object This Interactable

    Interactable.set(options)

    Reset the options of this Interactable

    Parameters

    1. options object The new settings to apply

    Returns: object This Interactablw

    Interactable.unset()

    Remove this interactable from the list of interactables and remove it's drag, drop, resize and gesture capabilities

    Returns: object interact

    interact.isSet(element)

    Check if an element has been set

    Parameters

    1. element Element The Element being searched for

    Returns: boolean Indicates if the element or CSS selector was previously passed to interact

    interact.on(type, listener, [useCapture])

    Adds a global listener for an InteractEvent or adds a DOM event to document

    Parameters

    1. type string The type of event to listen for
    2. listener function The function to be called on that event
    3. useCapture boolean useCapture flag for addEventListener

    Returns: object interact

    interact.off(type, listener, [useCapture])

    Removes a global InteractEvent listener or DOM event from document

    Parameters

    1. type string The type of event that was listened for
    2. listener function The listener function to be removed
    3. useCapture boolean useCapture flag for removeEventListener

    Returns: object interact

    interact.simulate(action, element, [pointerEvent])

    Simulate pointer down to begin to interact with an interactable element

    Parameters

    1. action string The action to be performed - drag, resize, etc.
    2. element Element The DOM Element to resize/drag
    3. pointerEvent object Pointer event whose pageX/Y coordinates will be the starting point of the interact drag/resize

    Returns: object interact

    interact.enableDragging([newValue])

    Returns or sets whether dragging is enabled for any Interactables

    Parameters

    1. newValue boolean true to allow the action; false to disable action for all Interactables

    Returns: boolean object The current setting or interact

    interact.enableResizing([newValue])

    Returns or sets whether resizing is enabled for any Interactables

    Parameters

    1. newValue boolean true to allow the action; false to disable action for all Interactables

    Returns: boolean object The current setting or interact

    interact.enableGesturing([newValue])

    Returns or sets whether gesturing is enabled for any Interactables

    Parameters

    1. newValue boolean true to allow the action; false to disable action for all Interactables

    Returns: boolean object The current setting or interact

    interact.debug()

    Returns debugging data

    Returns: object An object with properties that outline the current state and expose internal functions and variables

    interact.margin([newValue])

    Returns or sets the margin for autocheck resizing used in Interactable.getAction. That is the distance from the bottom and right edges of an element clicking in which will start resizing

    Parameters

    1. newValue number

    Returns: number interact The current margin value or interact

    interact.styleCursor(event)

    Returns or sets whether the cursor style of the document is changed depending on what action is being performed

    Parameters

    1. newValue boolean

    Returns: boolean interact The current setting of interact

    interact.autoScroll(options)

    Returns or sets whether or not actions near the edges of the window or specified container element trigger autoScroll by default

    Parameters

    1. options boolean object true or false to simply enable or disable or an object with margin, distance, container and interval properties

    Returns: object interact

    or

    Returns: boolean object false if autoscroll is disabled and the default autoScroll settings if it is enabled

    interact.snap([options])

    Returns or sets whether actions are constrained to a grid or a collection of coordinates

    Parameters

    1. options boolean object New settings

    true or false to simply enable or disable or an object with some of the following properties

    1. {
      1. mode : 'grid', 'anchor' or 'path',
      2. range : the distance within which snapping to a point occurs,
      3. actions: ['drag', 'resizex', 'resizey', 'resizexy'], an array of action types that can snapped (['drag'] by default) (no gesture)
      4. grid : {
        1. x, y: the distances between the grid lines,
      5. },
      6. gridOffset: {
        1. x, y: the x/y-axis values of the grid origin
      7. },
      8. anchors: [
      9. {
        1. x: x coordinate to snap to,
        2. y: y coordinate to snap to,
        3. range: optional range for this anchor
      10. }
      11. {
        1. another anchor
      12. }
      13. ]
    2. }

    Returns: object interact The default snap settings object or interact

    interact.inertia([options])

    Returns or sets inertia settings.

    See Interactable.inertia

    Parameters

    1. options boolean object New settings

    true or false to simply enable or disable or an object of inertia options

    Returns: object interact The default inertia settings object or interact

    interact.supportsTouch()

    Returns: boolean Whether or not the browser supports touch input

    interact.currentAction()

    Returns: string What action is currently being performed

    interact.stop(event)

    Ends the current interaction

    Parameters

    1. event Event An event on which to call preventDefault()

    Returns: object interact

    interact.dynamicDrop([newValue])

    Returns or sets whether the dimensions of dropzone elements are calculated on every dragmove or only on dragstart for the default dropChecker

    Parameters

    1. newValue boolean True to check on each move. False to check only before start

    Returns: boolean interact The current setting or interact

    interact.deltaSource([newValue])

    Returns or sets weather pageX/Y or clientX/Y is used to calculate dx/dy.

    See Interactable.deltaSource

    Parameters

    1. newValue string 'page' or 'client'

    Returns: string Interactable The current setting or interact

    interact.restrict([newValue])

    Returns or sets the default rectangles within which actions (after snap calculations) are restricted.

    See Interactable.restrict

    Parameters

    1. newValue object an object with keys drag, resize, and/or gesture and rects or Elements as values

    Returns: object The current restrictions object or interact

    interact.pointerMoveTolerance([newValue])

    Returns or sets the distance the pointer must be moved before an action sequence occurs. This also affects tolerance for tap events.

    Parameters

    1. newValue number The movement from the start position must be greater than this value

    Returns: number Interactable The current setting or interact

    interact.tryCatchEventListeners([newValue])

    Returns or sets whether errors thrown in InteractEvent listeners and delegated event listeners should be caught and logged safely or should be allowed to propagate and disrupt the event firing process.

    Parameters

    1. newValue boolean false to allow errors to propagate (default). true to handle errors internally.

    Returns: boolean Interactable The current setting or interact