Swapy

A framework-agnostic tool that converts any layout into a drag-to-swap one ...

Drag and dropLayout
TahaSh/swapyswapy.tahazsh.com/swapy

README

Swapy


A simple JavaScript tool for converting any layout you have to drag-to-swap layout


Docs


1. Install

Use your favorite package manager to install it.

  1. ``` sh
  2. pnpm install swapy
  3. ```

Or get it from CDN.

  1. ``` html
  2. <script src="https://unpkg.com/swapy/dist/swapy.min.js"></script>
  3. <script>
  4.   // You can then use it like this
  5.   const swapy = Swapy.createSwapy(container)
  6. </script>
  7. ```

2. Using Swapy

Below, I'm showing you a simple layout, but yours can be as complex as you want it to be.

Specify Slots and Items
To specify a slot, give its element data-swapy-slot="anyNameYouWant". Each slot can only contain a single item. Items are what you drag and drop.
To mark an element as an item, add this data attribute: data-swapy-item="anyNameYouWant".
By default, items are draggable from any spot. You can specify a handle by adding an element with data-swapy-handle (see content-b below).

You can customize the slot you are currently selecting by styling data-swapy-highlighted in your CSS.

  1. ``` html
  2. <div class="container">
  3.   <div class="section-1" data-swapy-slot="foo">
  4.     <div class="content-a" data-swapy-item="a">
  5.       !-- Your content for content-a goes here -->
  6.     </div>
  7.   </div>
  9.   <div class="section-2" data-swapy-slot="bar">
  10.     <div class="content-b" data-swapy-item="b">
  11.       !-- Your content for content-b goes here -->
  12.       <div class="handle" data-swapy-handle></div>
  13.     </div>
  14.   </div>
  16.   <div class="section-3" data-swapy-slot="baz">
  17.     <div class="content-c" data-swapy-item="c">
  18.       !-- Your content for content-c goes here -->
  19.     </div>
  20.   </div>
  21. </div>
  22. ```

Use Swapy

Get the container element that contains your slots and items, and pass it to createSwapy(). By default, it will use dynamic animation. You can change it using the animation config option.

  1. ``` js
  2. import { createSwapy } from 'swapy'

  4. const container = document.querySelector('.container')

  6. const swapy = createSwapy(container, {
  7.   animation: 'dynamic' // or spring or none
  8. })

  10. // You can disable and enable it anytime you want
  11. swapy.enable(true)
  12. ```

3. Listening to Events

You can listen to swap events to do things like storing the new order. To make it more convenient for you, the swap event returns three versions of the new order: map, object, and array.

  1. ``` js
  2. import { createSwapy } from 'swapy'

  4. const container = document.querySelector('.container')

  6. const swapy = createSwapy(container)

  8. swapy.onSwap((event) => {
  9.   console.log(event.data.object);
  10.   console.log(event.data.array);
  11.   console.log(event.data.map);

  13.   // event.data.object:
  14.   // {
  15.   //   'foo': 'a',
  16.   //   'bar': 'b',
  17.   //   'baz': 'c'
  18.   // }

  20.   // event.data.array:
  21.   // [
  22.   //   { slot: 'foo', item: 'a' },
  23.   //   { slot: 'bar', item: 'b' },
  24.   //   { slot: 'baz', item: 'c' }
  25.   // ]

  27.   // event.data.map:
  28.   // Map(3) {
  29.   // 'foo' => 'a',
  30.   // 'bar' => 'b',
  31.   // 'baz' => 'c'
  32.   // }
  33. })
  34. ```