interact.js

API Reference

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
    startAxis: 'x' || 'y' || 'xy',

    // 'xy' by default - don't restrict to one axis (move in any direction)
    // 'x' or 'y' to restrict movement to either axis
    // 'start' to restrict movement to the axis the drag started in
    lockAxis: 'x' || 'y' || 'xy' || 'start',

    // max number of drags that can happen concurrently
    // with elements of this Interactable. Infinity by default
    max: Infinity,

    // max number of drags that can target the same element+Interactable
    // 1 by default
    maxPerElement: 2
});

Interactable.dropzone([options])

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

Dropzones can receive the following events:

  • dropactivate and dropdeactivate when an acceptable drag starts and ends
  • dragenter and dragleave when a draggable enters and leaves the dropzone
  • dragmove when a draggable that has entered the dropzone is moved
  • 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. The value can be:

  • an Element - only that element can be dropped into this dropzone.
  • a string, - the element being dragged must match it as a CSS selector.
  • null - accept options is cleared - it accepts any 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 (intersection area) / (draggable area).
  • e.g. 0.5 for drop to happen when half of the area of the draggable is over the dropzone

    Use the checker option to specify a function to check if a dragged element is over this Interactable.

    interact(target)
    .dropChecker(function(dragEvent,         // related dragmove or dragend event
                          event,             // TouchEvent/PointerEvent/MouseEvent
                          dropped,           // bool result of the default checker
                          dropzone,          // dropzone Interactable
                          dropElement,       // dropzone elemnt
                          draggable,         // draggable Interactable
                          draggableElement) {// draggable element
    
      return dropped && event.target.hasAttribute('allow-drop');
    }

    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

    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

    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) {},
    
      edges: {
        top   : true,       // Use pointer coords to check for resize.
        left  : false,      // Disable resizing from left edge.
        bottom: '.resize-s',// Resize if pointer target matches selector
        right : handleEl    // Resize if pointer target is the given Element
      },
    
        // Width and height can be adjusted independently. When `true`, width and
        // height are adjusted at a 1:1 ratio.
        square: false,
    
        // Width and height can be adjusted independently. When `true`, width and
        // height maintain the aspect ratio they had when resizing started.
        preserveAspectRatio: false,
    
      // a value of 'none' will limit the resize rect to a minimum of 0x0
      // 'negate' will allow the rect to have negative width/height
      // 'reposition' will keep the width/height positive by swapping
      // the top and bottom edges and/or swapping the left and right edges
      invert: 'none' || 'negate' || 'reposition'
    
      // limit multiple resizes.
      // See the explanation in the @Interactable.draggable example
      max: Infinity,
      maxPerElement: 1,
    });

    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({
        onstart: function (event) {},
        onmove : function (event) {},
        onend  : function (event) {},
    
        // limit multiple gestures.
        // See the explanation in @Interactable.draggable example
        max: Infinity,
        maxPerElement: 1,
    });

    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.

    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.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 string An object eg. { x: 0, y: 0 } or string 'parent', 'self' or any CSS selector

    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([newValue])

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

    Parameters

    1. newValue 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.context()

    Gets the selector context Node of the Interactable. The default is window.document.

    Returns: Node The context Node of this Interactable

    Interactable.fire(iEvent)

    Calls listeners for the given InteractEvent type bound globally 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, [options])

    Binds a listener for an InteractEvent, pointerEvent or DOM event.

    Parameters

    1. eventType string array object The types of events to listen for
    2. listener function The function event (s)
    3. options object boolean options object or useCapture flag for addEventListener

    Returns: object This Interactable

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

    Removes an InteractEvent, pointerEvent or DOM event listener

    Parameters

    1. eventType string array object The types of events that were listened for
    2. listener function The listener function to be removed
    3. options object boolean options object or 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 Interactable

    Interactable.unset()

    Remove this interactable from the list of interactables and remove it's action capabilities and event listeners

    Returns: object interact

    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, interactable, element and interaction as parameters and returns an object with name property 'drag' 'resize' or 'gesture' and optionally an edges object with boolean 'top', 'left', 'bottom' and right props.

    Returns: Function Interactable The checker function or this Interactable

    interact('.resize-drag')
      .resizable(true)
      .draggable(true)
      .actionChecker(function (pointer, event, action, interactable, element, interaction) {
    
      if (interact.matchesSelector(event.target, '.drag-handle') {
        // force drag with handle target
        action.name = drag;
      }
      else {
        // resize from the top and right edges
        action.name  = 'resize';
        action.edges = { top: true, right: true };
      }
    
      return action;
    });

    Interactable.styleCursor([newValue])

    Returns or sets whether the the cursor should be changed depending on the action that would be performed if the mouse were pressed and dragged.

    Parameters

    1. newValue boolean

    Returns: boolean Interactable The current setting or this Interactable

    interact.maxInteractions([newValue])

    Returns or sets the maximum number of concurrent interactions allowed. By default only 1 interaction is allowed at a time (for backwards compatibility). To allow multiple interactions on the same Interactables and elements, you need to enable it in the draggable, resizable and gesturable 'max' and 'maxPerElement' options.

    Parameters

    1. newValue number Any number. newValue <= 0 means no interactions.

    Interactable.preventDefault([newValue])

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

  • 'always' to always prevent
  • 'never' to never prevent
  • 'auto' to let interact.js try to determine what would be best
  • Parameters

    1. newValue string true, false or 'auto'

    Returns: string Interactable The current setting or this Interactable

    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('#draggable').draggable(true);
    
    var rectables = interact('rect');
    rectables
        .gesturable(true)
        .on('gesturemove', function (event) {
            // ...
        });

    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, [options])

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

    Parameters

    1. type string array object The types of events to listen for
    2. listener function The function event (s)
    3. options object boolean options object or useCapture flag for addEventListener

    Returns: object interact

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

    Removes a global InteractEvent listener or DOM event from document

    Parameters

    1. type string array object The types of events that were listened for
    2. listener function The listener function to be removed
    3. options object boolean options object or useCapture flag for removeEventListener

    Returns: object interact

    interact.debug()

    Returns an object which exposes internal data

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

    interact.supportsTouch()

    Returns: boolean Whether or not the browser supports touch input

    interact.supportsPointerEvent()

    Returns: boolean Whether or not the browser supports PointerEvents

    interact.stop(event)

    Cancels all interactions (end events are not fired)

    Parameters

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

    Returns: object 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

    Interaction.start(action, target, element)

    Start an action with the given Interactable and Element as tartgets. The action must be enabled for the target Interactable and an appropriate number of pointers must be held down - 1 for drag/resize, 2 for gesture.

    Use it with interactable.<action>able({ manualStart: false }) to always start actions manually

    Parameters

    1. action object The action to be performed - drag, resize, etc.
    2. target Interactable The Interactable to target
    3. element Element The DOM Element to target

    Returns: object interact

    interact(target)
      .draggable({
        // disable the default drag start by down->move
        manualStart: true
      })
      // start dragging after the user holds the pointer down
      .on('hold', function (event) {
        var interaction = event.interaction;
    
        if (!interaction.interacting()) {
          interaction.start({ name: 'drag' },
                            event.interactable,
                            event.currentTarget);
        }
    });

    Interaction.doMove()

    Force a move of the current action at the same coordinates. Useful if snap/restrict has been changed and you want a movement with the new settings.

    interact(target)
      .draggable(true)
      .on('dragmove', function (event) {
        if (someCondition) {
          // change the snap settings
          event.interactable.draggable({ snap: { targets: [] }});
          // fire another move event with re-calculated snap
          event.interaction.doMove();
        }
      });

    Interaction.end([event])

    Stop the current action and fire an end event. Inertial movement does not happen.

    Parameters

    1. event PointerEvent
    interact(target)
      .draggable(true)
      .on('move', function (event) {
        if (event.pageX > 1000) {
          // end the current action
          event.interaction.end();
          // stop all further listeners from being called
          event.stopImmediatePropagation();
        }
      });