Swapy

Meet Swapy, a framework-agnostic tool that converts any layout into a drag-to-swap one with just a few lines of code.

View full docs

try dragging

December

2024

My Todos

Todo 1
Todo 2
Todo 3

Sales

New subscribers

700+

works with all frameworks

1. Install

Use your favorite package manager to install it.

pnpm install swapy

Or get it from CDN.

<script src="https://unpkg.com/swapy/dist/swapy.min.js"></script>
<script>
  // You can then use it like this
  const swapy = Swapy.createSwapy(container)
</script>

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="anyUniqueNameYouWant". 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="anyUniqueNameYouWant".

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.

<div class="container">
  <div class="section-1" data-swapy-slot="foo">
    <div class="content-a" data-swapy-item="a">
      <!-- Your content for content-a goes here -->
    </div>
  </div>

  <div class="section-2" data-swapy-slot="bar">
    <div class="content-b" data-swapy-item="b">
      <!-- Your content for content-b goes here -->
      <div class="handle" data-swapy-handle></div>
    </div>
  </div>

  <div class="section-3" data-swapy-slot="baz">
    <div class="content-c" data-swapy-item="c">
      <!-- Your content for content-c goes here -->
    </div>
  </div>
</div>

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.

import { createSwapy } from 'swapy'

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

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

// You can disable and enable it anytime you want
swapy.enable(true)

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.

import { createSwapy } from 'swapy'

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

const swapy = createSwapy(container)

swapy.onSwap((event) => {
  console.log(event.newSlotItemMap.asArray);
  console.log(event.newSlotItemMap.asObject);
  console.log(event.newSlotItemMap.asMap);

  // event.newSlotItemMap.asObject:
  // {
  //   'foo': 'a',
  //   'bar': 'b',
  //   'baz': 'c'
  // }

  // event.newSlotItemMap.asArray:
  // [
  //   { slot: 'foo', item: 'a' },
  //   { slot: 'bar', item: 'b' },
  //   { slot: 'baz', item: 'c' }
  // ]

  // event.newSlotItemMap.asMap:
  // Map(3) {
  // 'foo' => 'a',
  // 'bar' => 'b',
  // 'baz' => 'c'
  // }
})

View full docs

Want to learn how to use it with a framework?

Check out these framework integration guides:

Did you like Swapy?

Please give it a star on GitHub. Thank you!

You might also be interested in my other project, Blendy.