Swapy is a tool that transforms any layout into a drag-and-swap one with minimal coding. You can install it using a package manager or CDN, specify slots, and listen to events for customization. It integrates with multiple frameworks like React, Vue, and Svelte.
Features
Drag-and-Drop Conversion
Swapy allows you to convert any layout into a drag-and-drop interface using a few lines of code. You can specify slots and items with data attributes, enabling dynamic placement and rearrangement of items within specified slots.
Framework Agnostic
Swapy works with all frameworks, providing flexible integration options whether you are using React, Vue, Angular, or others. This ensures that you can incorporate drag-and-drop functionality regardless of your existing tech stack.
Event Listening
You can listen to various swap events such as the order of items being changed. These events can provide detailed information, like new item positions, which you can use to trigger additional actions in your application.
Package Manager Installation
You can install Swapy using a package manager like npm, pnpm, or yarn. Simply run the command 'pnpm install swapy' to add it to your project.
CDN Installation
Swapy can be included in your project via a CDN. Use the script tag with the 'https://unpkg.com/swapy/dist/swapy.min.js' URL to include it in your HTML, and initialize it with 'Swapy.createSwapy(container)'. This makes it easy to use without local installation.
Client-side Library
Swapy is a client-side library that requires the DOM to be loaded and the component to be mounted before creating a new Swapy instance.
useEffect Hook Support
In React, you can use useEffect with empty dependencies to set up Swapy. It ensures the component is ready before Swapy is initialized.
Swapy Instance Creation
The createSwapy function is used to initialize an instance of Swapy using a container reference.
Event Listeners Support
You can add event listeners to the Swapy instance, for example, to listen for item swapping events.
Component Destruction Handling
Swapy instance is destroyed on component unmount to prevent memory leaks, typically done in a useEffect cleanup function.
Client-side Library
Swapy is used as a client-side library to create swappable interfaces in Vue components.
onMounted Hook
Utilizes Vue's onMounted lifecycle hook to initialize Swapy after the DOM elements are loaded.
onUnmounted Hook
Uses Vue's onUnmounted lifecycle hook to destroy the Swapy instance, ensuring proper cleanup.
Event Listeners
Allows adding event listeners, such as 'swap' events, to react to changes made through the Swapy interface.
Vue Integration
Instructions and examples to integrate Swapy within a Vue.js application.
dndDestroy
Allows you to destroy the Swapy instance on component destroy, ensuring resources are properly cleaned up.
dndEventListeners
Lets you add event listeners to the Swapy instance for custom behavior, such as logging swap events.
dndContainer
Enables element binding to a container where the DOM is loaded, facilitating the creation of a Swapy instance.
Slot Definition
Define a slot by setting a data-swapy-slot attribute on an element with a unique name.
Item Definition
Define an item by setting a data-swapy-item attribute on an element with a unique name.
Swapy Instance Creation
Create a Swapy instance for a container using createswapy(container) and specify configuration options.
Handle Element
Allows you to specify a handle within an item to make it draggable only from that particular element. You add the 'data-swapy-handle' attribute inside the item you want to make draggable in a controlled manner.
No-Drag Element Attribute
Allows you to prevent certain elements from being draggable by adding the attribute data-swapy-no-drag to those elements. This is useful for managing specific areas that should not trigger a drag event.
Dynamic Animation
Provides a default animation style when swapping items. This style adds movement to the transition between swapped elements.
Spring Animation
Implements a spring-like motion during the transition between swapped elements, giving a bouncy effect.
No Animation
Disables animation during item swaps, resulting in immediate changes without transitional effects.
Enabled Option
Allows the Swapy instance to be initialized as either disabled or enabled. By default, all items are draggable and swappable, but you can disable it initially. Use `swapy.enable(true)` to enable it later.
Hover Swap Mode
Items are swapped as soon as you hover the dragging item on any slot. This setting is activated by setting swapMode to 'hover'.
Drop Swap Mode
Items are swapped when you drop the dragging item onto a slot. This is configured by setting swapMode to 'drop'.
Auto-scroll On Drag
Automatically scrolls the nearest scrollable container when you drag an item close to its edge. This is enabled by setting 'autoScrollOnDrag: true' in the configuration.
Drag on Hold
This feature allows you to start a dragging session by clicking and holding on an element for a moment. It can be enabled by setting the `dragOnHold` option to `true` in the configuration.
Drag Axis Configuration
You can configure the drag axis to be horizontal, vertical, or both using the 'dragAxis' option. The default allows dragging on both axes, but it can be set to 'x' for horizontal or 'y' for vertical.
Manual Swap
Allows for dynamic swapping in frameworks by handling DOM updates manually. This is useful for frameworks like React, Vue, and Svelte, where dynamic content changes require specific handling.
Enable or Disable Swapy Instance
This feature allows you to control the activation status of your Swapy instance. Initially enabled, you can disable it by using the method swapy.enable(false). To re-enable, use swapy.enable(true).
swapy.update()
Re-instantiate the Swapy instance when the DOM is updated. This is used when you add or remove items or slots from the Swapy container to ensure Swapy recognizes the changes.