Magnet.js is a JavaScript library that groups HTML elements and makes them attractable with each other

jQuery version

• Configure magnet attract distance
• Switch to stay in parent element
• Align to outer/inner edge of the others
• Align to the x/y center of the others
• Align to the x/y center of parent element

4 magnet groups that can attract the others in their own groups or all the other group members.

Extend the Basic demo with new features:

• Support arrow keys to move focused box (also support a/w/d/s keys)
• Configure px unit of arrow_ (
• unit < distance would cause the box stuck with the others when attracted

git clone https://github.com/lf2com/magnet.js.git
cd magnet.js
npm install .

CAUTION: Magnet.js is not tested on NodeJS environment. It uses document and eventListener related functions.

npm install @lf2com/magnet.js
# Or
npm install https://github.com/lf2com/magnet.js

Import

import Magnet from '@lf2com/magnet.js';
// Or
const Magnet = require('@lf2com/magnet.js');

The required files are ./index.js and ./libs/*.js. All dependencies in ./package.json are only used for building a packaged/minified JS file as ./magnet.min.js. Since the code registered as window.Magnet. You can build a browser-used magnet.min.js with the following commands:

npm run build

Build jQuery Plugin

Build ./jquery-magnet.min.js

npm run jquery-build

Build All

Build both ./magnet.min.js and ./jquery-magnet.min.js

npm run all-build

Debug Build

Append -debug on any build command

npm run build-debug

# for jQuery
npm run jquery-build-debug

# for both
npm run all-build-debug

Download from this repository or use your own built: magnet.min.js

<!-- include script -->
<script src="PATH/TO/magnet.min.js"></script>

<script>
  console.log(window.Magnet); // here it is
</script>

jQuery Plugin

NOTICE: Please include jQuery library before incluing jquery-magnet.min.js

<script src="PATH/TO/jQuery.js"></script>
<script src="PATH/TO/jquery-magnet.min.js"></script>
<script>
  (function($) {
    console.log($.magnet); // here it is
  })(jQuery);
</script>

Create a magnet group. All the elements added into the group would be applied the attract behaviors.

let magnet = new Magnet();

jQuery

Create a new group

$.magnet(options?)

let options = {
  distance: 15,
  stayInParent: true,
};
let $magnet = $.magnet(options);

Add HTML elements into the group

magnet.add(document.querySelectorAll('.magnet')); // return this

Or add HTML element when creating a group

let magnet = new Magnet(document.querySelectorAll('.magnet'));

Flexable ways to add elements

magnet.add(
  document.querySelectorAll('.magnet'),
  document.querySelectorAll('.other-magnet'),
  document.getElementById('major-magnet')
);

// the same as above
magnet
  .add(document.querySelectorAll('.magnet'))
  .add(document.querySelectorAll('.other-magnet'))
  .add(document.getElementById('major-magnet'));

jQuery

$magnet.add(...DOMs)

Add elements to an existing group

$.fn.magnet(options?)

Add element to a new group

let $magnet = $('.magnet').magnet(options);

Remove HTML elements from the group

Keep the positon changed by the magnet

magnet.remove(document.querySelector('.magnet')); // return this

Remove the positions changed by the magnet

magnet.removeFull(document.querySelector('.magnet')); // return this

Flexable ways to remove elements

magnet.remove(
  document.querySelectorAll('.magnet'),
  document.querySelectorAll('.other-magnet'),
  document.getElementById('major-magnet')
);

// the same as above
magnet
  .remove(document.querySelectorAll('.magnet'))
  .remove(document.querySelectorAll('.other-magnet'))
  .remove(document.getElementById('major-magnet'));

jQuery

$magnet.remove(...DOMs)

$magnet.removeFull(...DOMs)

Remove all the HTML elements from the group

Keep the position changed by the magnet

magnet.clear();

Remove the position changed by the magnet

magnet.clearFull();

jQuery

$magnet.clear()

$magnet.clearFull()

Synchronize mouse coordinates with the dragged block when the parent is scaled

_Default: 1

Get/set scale

magnet.scale(1.2); // set: value, return this
magnet.scale(); // get: 1.2

Alias

.setScale(value)

magnet.setScale(1.2); // set to 1.2

.getScale()

magnet.getScale(); // get 1.2

jQuery

$magnet.scale(value?)

_

Distance for elements to attract others in the same group

Default: 0 (px)

Get/set distance

magnet.distance(15); // set: unit px, return this
magnet.distance(); // get: 15

Alias

.setDistance(px)

magnet.setDistance(15); // set to 15

.getDistance()

magnet.getDistance(); // get 15

jQuery

$magnet.distance(px?)

Attractable between group members

Default: true

NOTICE: Setting to false has the same effect as pressing ctrl key

Get/set attractable

magnet.attractable(true); // set to attract members, return this
magnet.attractable(); // get: true

Alias

.setAttractable(enabled)

magnet.setAttractable(true); // set to true

.getAttractable()

magnet.getAttractable(); // get true

jQuery

$magnet.attractable(enabled?)

Allow to press ctrl key to be unattractable temporarily

Default: true

NOTICE: Pressing ctrl key makes group members unattractable, any magnet related event will not be triggered

Get/set allow ctrl key

magnet.allowCtrlKey(true); // set to allow ctrl key, return this
magnet.allowCtrlKey(); // get: true

Alias

.setAllowCtrlKey(enabled)

magnet.setAllowCtrlKey(true); // set to true

.getAllowCtrlKey()

magnet.getAllowCtrlKey(); // get true

jQuery

$magnet.allowCtrlKey(enabled?)

Allow to drag element by mouse/touch

Default: true

Get/set allow drag

magnet.allowDrag(true); // set to allow drag, return this
manget.allowDrag(); // get: true

Alias

.setAllowDrag(enabled)

magnet.setAllowDrag(true); // set to true

.getAllowDrag()

magnet.getAllowDrag(); // get true

jQuery

$magnet.allowDrag(enabled?)

Use relative unit % or absolute unit px

Default: false

Get/set use relative unit

magnet.useRelativeUnit(true); // set to use relative unit, return this
magnet.useRelativeUnit(); // get: true

Alias

.setUseRelativeUnit(enabled)

magnet.setUseRelativeUnit(true); // set to true

magnet.getUseRelativeUnit(); // get true

jQuery

$magnet.useRelativeUnit(enabled?)

Magnet supports the following alignments:

Get/set enabled of alignment

magnet.alignOuter(true); // set: align to element outside edges, return this
magnet.alignInner(false); // set: align to element inside edges, return this
magnet.alignCenter(true); // set: align to element middle line, return this
magnet.alignParentCenter(false); // set: alien to parent element middle line, return this

magnet.alignOuter(); // get: true

Alias

.enabledAlign{Prop}(enabled?)

magnet.enabledAlignOuter(true); // set to true
magnet.enabledAlignParentCenter(false); // set to false

magnet.enabledAlignOuter(); // get: true
magnet.enabledAlignParentCenter(); // get: false

.setEnabledAlign{Prop}(enabled)

magnet.setEnabledAlignOuter(true); // set to true

.getEnabledAlign{Prop}()

magnet.getEnabledAlignOuter(); // get true

jQuery

$magnet.align{Prop}(enabled?)

CAUTION:

• Parent may NOT be the 1st parentNode of the current element._
• Parent is the first matched parentNode whose style.position is not static
• All the top/left offset of magnet members is based on the parent element

Force elements of group not to be out of the edge of parent element

Default: false

Get/set stay inside of the parent

magnet.stayInParent(true); // set: not to move outside of the parent element, return this
magnet.stayInParent(); // get: true

Alias

.stayInParentEdge(enabled?)

magnet.stayInParentEdge(true); // set to true
magnet.stayInParentEdge(); // get: true

.stayInParentElem(enabled?)

magnet.stayInParentElem(true); // set to true
magnet.stayInParentElem(); // get true

Another alias

.setStayInParent(enabled)

magnet.setStayInParent(true); // set to true

.getStayInParent()

magnet.getStayInParent(); // get true

jQuery

$magnet.stayInParent(enabled?)

Magnet supports the following events:

Each event has the following members in the detail of event object:

Add event listener

magnet.on('magnetenter', function(evt) {
  let detail = evt.detail;
  console.log('magnetenter', detail); // detail info of attract elements
  console.log('source', detail.source); // current HTML element
  console.log('targets', detail.x, detail.y); // current attracted of both axises
});

magnet.on('magnetleave', function(evt) {
  let detail = evt.detail;
  console.log('magnetleave', detail);
  console.log('source', detail.source);
  console.log('targets', detail.x, detail.y); // the last attracted of both axises
});

magnet.on('magnetchange', function(evt) {
  let detail = evt.detail;
  console.log('magnetchange', detail);
  console.log('source', detail.source);
  console.log('targets', detail.x, detail.y); // the newest attracted of both axises
});

// the same as above
magnet.on('magnetstart', function(evt) {
  // do something
}).on('magnetchange', function(evt) {
  // do something
}).on('magnetend', function(evt) {
  // do something
});

jQuery

$magnet.on(eventNames, functions)

Remove event listeners

magnet.off('magnetenter magnetleave magnetchange'); // remove event listeners

// the same as above
magnet
  .off('magnetenter')
  .off('magnetleave')
  .off('magnetchange');

jQuery

$magnet.off(eventNames)

Magnet members supports the following events:

Events of attract and unattract have the following members in the detail of event object:

let elem = document.querySelector('.block');
magnet.add(elem);

function onAttract(evt) {
  let detail = evt.detail;
  console.log('attract', detail); // detail info of attract elements
  console.log('targets', detail.x, detail.y); // current attracted of both axises
}
function onUnattract(evt) {
  let detail = evt.detail;
  console.log('unattract', detail);
  console.log('targets', detail.x, detail.y); // the last attracted of both axises
}

// add event listener
elem.addEventListener('attract', onAttract);
elem.addEventListener('unattract', onUnattract);

// remove event listener
elem.removeEventListener('attract', onAttract);
elem.removeEventListener('unattract', onUnattract);

jQuery

// the same as above
$(elem)
  .on('attract', onAttract)
  .on('unattract', onUnattract);

$(elem)
  .off('attract unattract');

Events of attracted and unattracted have the target member in the detail of event object

function onAttracted(evt) {
  let dom = evt.detail;
  console.log('attracted', dom); // be attracted by dom
}
function onUnattracted(evt) {
  let dom = evt.detail;
  console.log('unattracted', dom); // be unattracted by dom
}

// add event listener
elem.addEventListener('attracted', onAttracted);
elem.addEventListener('unattracted', onUnattracted);

// remove event listener
elem.removeEventListener('attracted', onAttracted);
elem.removeEventListener('unattracted', onUnattracted);

jQuery

// the same as above
$(elem)
  .on('attracted', onAttracted)
  .on('unattracted', onUnattracted);

$(elem).off('attracted unattracted');

function onAttractStart(evt) {
  let rect = evt.detail;
  console.log('attract start', rect); // rectangle of dom
}
function onAttractEnd(evt) {
  let rect = evt.detail;
  console.log('attract end', rect); // rectangle of dom
}

// add event listener
elem.addEventListener('attractstart', onAttractStart);
elem.addEventListener('attractend', onAttractEnd;

// remove event listener
elem.removeEventListener('attractstart', onAttractStart);
elem.removeEventListener('attractend', onAttractEnd

jQuery

// the same as above
$(elem)
  .on('attractstart', onAttractStart)
  .on('attractend', onAttractEnd);

$(elem).off('attractstart attractend');

NOTICE: Call preventDefault() to ignore attraction if need

function onAttractMove(evt) {
  let { rects, attracts } = evt.detail;
  let { origin, target } = rects;
  let { current, last } = attracts;
  
  // do something
  // ...

  evt.preventDefault(); // call this to ignore attraction if need
}

elem.addEventListener('attractmove', onAttractMove); // add event listener
elem.removeEventListener('attractmove', onAttractMove); // remove event listener

jQuery

// the same as above
$(elem).on('attractmove', onAttractMove);

$(elem).off('attractmove');

Check the relationships between source and all the other group members

Default sourceRect is the rectangle of sourceDOM

Default alignments is the outer/inner/center settings of magnet

magnet.add(elem);
magnet.check(elem, ['topToTop', 'bottomToBottom']); // get the result of 'topToTop' and 'bottomToBottom' between the other members

// the same as above
magnet.check(elem, elem.getBoundingClientRect(), ['topToTop', 'bottomToBottom']);

jQuery

$magnet.check(sourceDOM[, sourceRect[, alignments]])

Change the position of target member for the input position with checking the attracting relationships between source and all the other group members

Default sourceRect is the rectangle of sourceDOM

Default attractable is the value of attractable

let { top, right, bottom, left } = elem.getBoundingClientRect();
let offset = {
  x: 15,
  y: 10
};
let rect = {
  top: (top-offset.y),
  right: (right-offset.x),
  bottom: (bottom-offset.y),
  left: (left-offset.x),
};
magnet.add(elem);
magnet.handle(elem, rect, true); // move the member to the new rectangle position with the attracting relationship, return this

jQuery

$magnet.handle(sourceDOM[, sourceRect[, attractable]])

Directly change the position of member that is faster than .handle(...)

Default sourceRect is the rectangle of sourceDOM

Default useRelativeUnit is the value of .getUseRelativeUnit()

let { top, right, bottom, left } = elem.getBoundingClientRect();

magnet.setMemberRectangle(elem, rect);

The group passes the info to target function before/after/do applying the change to target element

NOTICE: The function will be called with rectangle infos and attract infos as long as dragging the target element

Set to a function for confirming the change

function beforeAttractFunc(dom, { origin, target }, { current, last }) {
  console.log(this); // manget

  if (MAKE_SOME_CHANGES) {
    // apply other rectangle info
    return {
      top: (target.top - 1),
      right: (target.right + 1),
      bottom: (target.bottom + 1),
      left: (target.left - 1),
    };
  } else if (NO_ATTRACTION) {
    return false; // ignore attraction
  } else if (STILL_NO_ATTRACTION) {
    return origin; // the same as no attraction
  }

  // if went here, it would apply default change
};

magnet.beforeAttract = beforeAttractFunc; // set function
console.log(magnet.beforeAttract); // print function

magnet.beforeAttract = null; // unset function

jQuery

$magnet.beforeAttract(function(targetDom, rectangleInfos, attractInfos)?)

$magnet.beforeAttract(beforeAttractFunc); // set function
$magnet.beforeAttract(); // get beforeAttractFunc

$magnet.beforeAttract(null); // unset function (input non-function value)

Set the displacement handly which means the user has to set the style of DOM to apply the position change if need

magnet.doAttract = function(dom, { origin, target }, { current, last }) {
  const { top, right, bottom, left } = origin;
  const { x, y } = current;
  const px = (p) => `${p}px`;

  if (x && y && x.element === y.element) {
    // attract current targets
    const elem = x.element;
    const { width, height } = x.rect;
    const move = (type) => {
      switch (type) {
        case 'topToTop': return elem.style.top = px(top);
        case 'rightToRight': return elem.style.left = px(right-width);
        case 'bottomToBottom': return elem.style.top = px(bottom-height);
        case 'leftToLeft': return elem.style.left = px(left);
        case 'topToBottom': return elem.style.top = px(top-height);
        case 'bottomToTop': return elem.style.top = px(bottom);
        case 'rightToLeft': return elem.style.left = px(right);
        case 'LeftToRight': return elem.style.left = px(left-width);
        case 'xCenter': return elem.style.left = px((right+left-width)/2);
        case 'yCenter': return elem.style.top = px((top+bottom-height)/2);
      }
    }
    move(x.type);
    move(y.type);
  }

  // keep original position
  dom.style.top = px(top);
  dom.style.left = px(left);
});

jQuery

$magnet.doAttract(function(targetDom, rectangleInfos, attractInfos)?)

See what changed after attracting

jQuery

$magnet.afterAttract(function(targetDom, rectangleInfos, attractInfos)?)

Check if rect is a rectangle like object with the following object members and rules:

NOTICE: Default use 0.0000000001 for bias of calculation

let rect = { top: 1, right: 2, bottom: 3, left: 4 };
Magnet.isRect(rect); // false: right < left
rect.right = 5;
Magnet.isRect(rect); // true

rect.x = 3;
Magnet.isRect(rect); // false: x != left
rect.x = rect.left;

rect.width = 2;
Magnet.isRect(rect); // false: width != (right - left)

Return a rectangle object if rect is a HTML element or a valid rectangle like object:

Magnet.stdRect(rect); // get a rectangle object

Measure distance between 2 elements/rectangles

Options of measurement:

let rectA = { top: 0, right: 3, bottom: 1, left: 2 };
let rectB = { top: 10, right: 13, bottom: 11, left: 12 };
Magnet.measure(rectA, rectB); // MeasureResult object

Alias

Magnet.diffRect(source, target[, options])

Magnet.diffRect(rectA, rectB);

See measurement result object

To reduce the usless calculations of measurement, it's recommended to call Magnet.measure/Magnet.diffRect independently and handle the results handly to get what you really want.

NOTICE: All the properties inherit from alignment properties

NOTICE: The following properties are DEPRECATED

Property	Type	Replacement
topToTop	Number	results.topToTop
topToBottom	Number	results.topToBottom
rightToRight	Number	results.rightToRight
rightToLeft	Number	results.rightToLeft
bottomToTop	Number	results.bottomToTop
bottomToBottom	Number	results.bottomToBottom
xCenter	Number	results.xCenter
yCenter	Number	results.yCenter

MIT Copyright @ Wan Wan