@lf2com/magnet.js v2.0.1

Magnet.js

Magnet.js is a JavaScript library making HTML elements attractable to each other.

Demo

Basic

Samples of using magnet.js:

• HTML
• JavaScript
• jQuery
• React.

Groups

Creates magnet blocks of different groups.

Get Started

:warning: Since v2.0.0, magnet.js has become a HTML element for us to wrap other elements or directly use it as a attractable block.

Add magnet.js to your HTML file:

<script defer src="https://unpkg.com/@lf2com/magnet.js@latest/magnet.min.js"></script>
<!-- or -->
<script defer src="https://cdn.jsdelivr.net/gh/lf2com/magnet.js@latest/magnet.min.js"></script>

We can use magnets directly in HTML:

<magnet-block
  style="width: 100px; height: 50px; background: #fcc;"
  attract-distance="10"
  align-to="outer|center"
>
  foo
</magnet-block>

<magnet-block attract-distance="10" align-to="outer|center">
  <div style="width: 100px; height: 50px; background: #fcc;">
    bar
  </div>
</magnet-block>

Or in JavaScript code:

const magnet = document.createElement('magnet-block');

magnet.setAttribute('attract-distance', '10');
magnet.setAttribute('align-to', 'outer|center');
// or
magnet.attractDistance = 10;
magnet.alignTos = ['outer', 'center'];

magnet.style.setProperty('width', '100px');
magnet.style.setProperty('height', '50px');
magnet.style.setProperty('background', '#fcc');
magnet.innerText = 'foo';
document.body.append(magnet);

Since magnet.js is an element, we can handle it with jQuery:

$('<magnet-block>')
  .attr({
    'attract-distance': '10',
    'align-to': 'outer|center',
  })
  .css({
    width: '100px',
    height: '50px',
    background: '#fcc',
  })
  .html('foo')
  .appendTo($('body'));

Of course we can use it in React:

const Magnet = () => (
  <magnet-block
    style={{
      width: '100px',
      height: '50px',
      background: '#fcc',
    }}
    attract-distance="10"
    align-to="outer|center"
  >
    foo
  </magnet-block>
);

Build

Build magnet.js with the command:

npm run build

The built would be at ./dist/magnet.min.js.

Magnet Nodes

There are 2 magnet elements: \<magnet-block> and \<magnet-pack>.

\<magnet-block>

Magnet block can be dragged and attracted by other magnets.

<magnet-block>
  <div style="padding: 1em; background-color: #eee;">
    magnet
  </div>
</magnet-block>

<!-- or directly use <magnet-block> -->
<magnet-block style="padding: 1em; background-color: #eee;">
  magnet
</magnet-block>

\<magnet-pack>

Magnet pack is unable to be dragged but it defines the default values for it's sub magnets. The sub manget blocks would reference to the nearest parent magnet pack for the attribute value if it doesn't have assigned the corresponding values.

<magnet-pack attract-distance="20">
  <!-- distance of attraction is 10 -->
  <magnet-block attract-distance="10">
    10
  </magnet-block>

  <!-- distance of attraction is 20 -->
  <magnet-block>
    default
  </magnet-block>
</magnet-pack>

Properties

Settable properties are defined as the confuration values of magnet element. If the magnet has no some magnet settings, it would reference to the nearest parent magnet having the value. Otherwise the value would be the default one.

Multiple Values

If a property accepts multiple values. Use any of the following character as separator: |, ,, ;, or space.

.disabled

Type of getting value: boolean

Default: false

If set, the magnet would be unable to be dragging and attracted.

<!-- disabled magnet -->
<magnet-block disabled>
  magnet
</magnet-block>

// disable magnet
magnet.disabled = true;
// or
magnet.setAttribute('disabled', '');

// get disabled
console.log('Disabled:', magnet.disabled);
// or
console.log('Disabled:', magnet.hasAttribute('disabled'));

.group

Type of getting value: string | null

Default: null as ungrouped

The group of magnet element. Once we assign a group for a magnet, it would only attract magnets in the same group. If no group is assigned, the magnet can attract all magnets including grouped ones.

<!-- set group -->
<magnet-block group="alpha">
  alpha
</magnet-block>
<magnet-block group="beta">
  beta
</magnet-block>
<magnet-block>
  ungrouped
</magnet-block>

// set group
magnet.group = 'alpha';
// or
magnet.setAttribute('group', 'alpha');

// get group
console.log('Group:', magnet.group);
// or
console.log('Group:', magnet.getAttribute('group'));

.parentMagnet

Type of getting value: Magnet

Returns the nearest parent magnet node.

The .parentMagnet of grouped magnet would be the nearest parent magnet in the same group or ungrouped one.

// get parent magnet
console.log('Nearest parent magnet:', magnet.parentMagnet);

.unattractable

Type of getting value: boolean

Default: false

If set, the magnet would not be attracted.

<!-- set unattractable -->
<magnet-block unattractable>
  magnet
</magnet-block>

// set unattractable
magnet.unattractable = true;
// or
magnet.setAttribute('unattractable', '');

// get unattractable
console.log('Unattractable:', magnet.unattractable);
// or
console.log('Unattractable:', magnet.hasAttribute('unattractable'));

.unmovable

Type of getting value: boolean

Default: false

If set, the magnet would not be dragged.

<!-- set unmovable -->
<magnet-block unmovable>
  magnet
</magnet-block>

// set unmovable
magnet.unmovable = true;
// or
magnet.setAttribute('unmovable', '');

// get unmovable
console.log('Unmovable:', magnet.unmovable);
// or
console.log('Unmovable:', magnet.hasAttribute('unmovable'));

.attractDistance

Type of getting value: number

Default: 10

Distance for magnet being dragged to attract other magnets.

We don't define the distance for magnet to be attracted.

<!-- set distance of attraction -->
<magnet-block attract-distance="20">
  magnet 20
</magnet-block>

<!-- default distance of attraction -->
<magnet-block>
  magnet default
</magnet-block>

// set distance of attraction
magnet.attractDistance = 20;
// or
magnet.setAttribute('attract-distance', '20');

// get distance of attracion in number
console.log('Attraction distance:', magnet.attractDistance);
// or in string
console.log('Attraction distance:', magnet.getAttribute('attract-distance'));

.alignTos

Type of getting value: string[]

Default: ['outer', 'center', 'extend']

Accepts multiple values.

Sides of rectangle that can be converted to alignments for magnet aligning to other magnets:

<!-- set align to -->
<magnet-block align-to="outer|extend">
  magnet
</magnet-block>

// set align to
magnet.alignTos = ['outer', 'extend'];
// or
magnet.alignTos = 'outer|extend';
// oe
magnet.setAttribute('align-to', 'outer|extend');

// get align-to in array
console.log('Align to:', magnet.alignTos);
// or in string
console.log('Align to:', magnet.getAttribute('align-to'));

.alignToParents

Type of getting value: string[]

Default: []

Accepts multiple values.

Sides of rectangle that can be converted to alignments for magnet aligning to it's parent element.

<!-- set align to parent -->
<magnet-block align-to-parent="inner|center">
  magnet
</magnet-block>

// set align to parent
magnet.alignToParents = ['inner', 'center'];
// or
magnet.alignToParents = 'inner|center';
// oe
magnet.setAttribute('align-to-parent', 'inner|center');

// get align-to-parent in array
console.log('Align to parent:', magnet.alignToParents);
// or in string
console.log('Align to parent:', magnet.getAttribute('align-to-parent'));

.alignments

Type of getting value: string[]

Returns the side-to-side alignments from magnet to other magnets. The values are converted from .alignTos.

// get alignments
console.log('Alignments:', magnet.alignments);

.parentAlignments

Type of getting value: string[]

Returns the side-to-side alignments from magnet to it's parent element. The values are converted from .alignToParents.

// get alignments to parent
console.log('Alignments to parent:', magnet.parentAlignments);

.crossPrevents

Type of getting value: string[]

Default: []

Accepts multiple values.

Prevents magnet from crossing specific targets such as parent:

<!-- set cross prevent -->
<magnet-block cross-prevent="parent">
  magnet
</magnet-block>

// set cross prevent
magnet.crossPrevents = ['parent'];
// or
magnet.crossPrevents = 'parent';
// or
magnet.setAttribute('cross-prevent', 'parent');

// get cross-prevent in array
console.log('Cross prevent:', magnet.crossPrevents);
// or in string
console.log('Cross prevent:', magnet.getAttribute('cross-prevent'));

.magnetRect

Returns temporarily created rectangle of magnet.

.magnetRect would not be updated util calling .resetMagnetRect

// get rectangle
console.log('Magnet rect:', magnet.magnetRect);

.parentPack

Returns temporarily created pack of the parent element of magnet.

.parentPack would not be updated util calling .resetParentPack

const parentPack = magnet.parentPack;

// get parent element
console.log('Parent element:', parentPack.raw);
// get parent rectangle
console.log('Parent rect:', parentPack.rect);

.targetMagnetPacks

Returns temporarily created packs of attractable magnets.

.targetMagnetPacks would not be updated util calling .resetTargetMagnetPacks

// get target magnet packs
console.log('Attractable magnet packs:', magnet.targetMagnetPacks);

.lastMagnetOffset

Returns the last offset in point of magnet.

const { x, y } = magnet.lastMagnetOffset;

// get last offset
console.log(`Last offset: (${x}, ${y})`);

.bestAttraction

Returns the best attraction in the last attraction.

const { x, y } = magnet.bestAttraction;

// get best attraction result
console.log('Best attraction on x-axis:', x);
console.log('Best attraction on y-axis:', y);

Methods

Magnet methods handle stuffs related to magnet such as alignment, distance, attraction, and position.

Static

Magnet.getAlignmentsFromAlignTo(alignTo)

Returns the array of alignments converted from alignTo values.

// get alignments of align-to
console.log('Alignments:', Magnet.getAlignmentsFromAlignTo('inner'));

// get alignments of align-tos
console.log('Alignments:', Magnet.getAlignmentsFromAlignTo(['outer', 'inner']));

Magnet.getMagnetAttractionOffset(attraction)

Returns the offset in point from attraction result.

Instance

.traceMagnetAttributeValue(attrName)

Returns the value of specific attribute name of magnet. If the magnet doesn't have the value, it would reference to the nearest parent magnet having the value. Or return null rather than global default value.

// get group
const group = magnet.traceMagnetAttributeValue('group');
// equals to (due to the default value is `null` too)
const group = magnet.group;

<!-- custom attribute -->
<magnet-pack some-attr="some-value">
  <magnet-block id="magnet">
    magnet
  </magnet-block>
</magnet-pack>

<script>
  const magnet = document.getElementById('magnet');

  // trace the custom attribute
  magnet.traceMagnetAttributeValue('some-attr'); // 'some-value'
</script>

.resetMagnetRect()

Removes the temporarily created rectangle of the magnet.

.resetparentPack()

Removes the temporarily created pack of the magnet parent element.

.resetTargetMagnetPacks()

Removes the temporarily created packs of the magnet attractable targets.

.getOtherMagnets()

Returns all other magnet nodes except magnet packs and the magnet caller.

.getAttractableMagnets()

Returns all magnet elements attractable to the magnet caller.

Consideration:

.judgeMagnetDistance(distance, options?)

Returns true if distance passes the judgement.

This method would be called for judging distance result on any method related to attraction.

Properties of options:

.judgeMagnetDistanceInParent(distance, options?)

The same as .judgeMagnetDistance but also consider a wrapper as the parent.

Properties of options:

.judgeMagnetAttraction(attraction)

Returns true if attraction passes the judgement.

.judgeMagnetMovement(pack)

Returns true if the movement of pack passes the judgement.

.rawDistanceTo(target, alignment)

Returns the value of distance from magnet caller to target on specific alignment.

.distanceTo(target, alignment)

Returns the result of distance from magnet caller to target on specific alignment.

.attractionTo(target, options?)

Returns the result of attraction from magnet caller to target.

Properties of options:

.attractionToParent(options?)

The same as .attractionTo but target is the parent of magnet caller.

Different default values of options:

.multiAttractionsTo(targets, options?)

Returns the results of attractions from magnet caller to targets.

The properties of options extends that of .attractionTo:

.getMagnetAttractionResultOfPosition(position, options?)

Returns the result of final position and attraction after considering position and options:

Properties of options:

.getMagnetAttractionResultOfPosition(x, y, options?)

The same as .getMagnetAttractionResultOfPosition(point, options?) but the input is (x, y).

.resetMagnetOffset()

Resets the offset of magnet to (0, 0).

.setMagnetOffset(dx, dy)

Sets the offset of magnet to (dx, dy).

.setMagnetOffset(offset)

The same as .setMagnetOffset but the input is Point.

.setMagnetPosition(x, y)

Sets the position of magnet to (x, y) without any judgement.

.setMagnetPosition(point)

The same as .setMagnetPosition but the input is Point.

Events

Events for magnet elements.

magnetstart

Cancelable: true

Magnet would not be dragged if the event is canceled.

Dispatches on starting to drag a magnet.

Properties of event.detail:

magnetmove

Cancelable: true

Magnet would not move at that step if the event is canceled.

Dispatches on dragging a magnet.

Properties of event.detail extend those of magnetstart:

magnetend

Cancelable: false

Dispatches on the end of dragging a magnet.

attract

Cancelable: true

The magnet would not attract the target magnet if the event is canceled.

Dispatches on the magnet attracting other magnet.

Properties of event.detail:

attracted

Cancelable: false

Dispatches on the magnet being attracted by other magnet.

Properties of event.detail:

attractmove

Cancelable: false

Dispatches on the magnet already attracting a magnet and still on moving.

Properties of event.detail are the same as attract.

attractedmove

Cancelable: false

Dispatches on the magnet being attracted by other magnet and it's still on moving.

Properties of event.detail are the same as attract.

unattract

Cancelable: false

Dispatches on the magnet unattracting a magnet.

Properties of event.detail are the same as attract.

unattracted

Cancelable: false

Dispatches on the magnet being unattracted by other magnet.

Properties of event.detail:

Types

Rectable

Defines objects that are able to be converted to rectangle:

• DOMRect
• HTMLElement
• document
• window

Point

Uses DOMPoint as the type of point (x, y).

Properties of point:

Rectangle

Uses DOMRect as the type of rectangle.

Properties of rectangle:

Pack

Wraps the source and its rectangle.

new Pack(source, rect?)

rect represents the rectangle of source since the rectangle may not be the same as the current one of source.

If rect is undefined, source must be rectable so that the rect could be generated from source.

Properties of pack object:

Distance

Wraps the info from source to target.

Properties of distance object:

Attraction

Wraps the result(s) of source attracting to target(s).

Properties of attraction object:

AttractionBest

Wraps the best distance results on axes of x and y.

Properties of best attraction object:

License

MIT Copyright @ Wan Wan