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/dist/magnet.min.js"></script>
<!-- or -->
<script defer src="https://cdn.jsdelivr.net/gh/lf2com/magnet.js@latest/dist/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.

Nodes of Magnet.js

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 configuration 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 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 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 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 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 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 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 value: string[]

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

Accepts multiple values.

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

| Name | Description | | -: | :- | | outer | Align to the outer sides of target | | inner | Align to the inner sides of target | | center | Align to the center lines of target | | extend | Align to extended line of assigned alignment including outer, inner and center |

<!-- 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 value: string[]

Default: []

Accepts multiple values.

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

| Name | Description | | -: | :- | | inner | Align to the inner sides of target | | center | Align to the center lines of target |

<!-- 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 value: string[]

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

| Name | Align to | Description | | -: | :-: | :- | | topToTop | inner | Source top to target top | | topToBottom | outer | Source top to target bottom | | rightToRight | inner | Source right to target right | | rightToLeft | outer | Source right to target left | | bottomToTop | outer | Source bottom to target top | | bottomToBottom | inner | Source bottom to target bottom | | leftToRight | outer | Source left to target right | | leftToLeft | inner | Source left to target left | | xCenterToXCenter | center | The center of source left and right to the center of target left and right | | yCenterToYCenter | center | The center of source top and bottom to the center of target top and bottom |

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

.parentAlignments

Type of value: string[]

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