Swapy

https://swapy.tahazsh.com/docs/installation
Admin
Swapy is a JavaScript library for creating interactive drag-and-drop interfaces, enabling features...
Tokens:5,872
Snippets:15
Trust Score:7.4
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install Swapy using NPM, PNPM, or Yarn

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Install the Swapy library using your preferred Node.js package manager. This command fetches the latest version and includes TypeScript definitions.

```bash
npm install swapy
# or
pnpm install swapy
# or
yarn add swapy
```

--------------------------------

### Basic Swapy Implementation in HTML and JavaScript

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Demonstrates a basic setup for Swapy with a 3-item grid layout. It includes HTML structure for slots and items, CSS for styling, and JavaScript to initialize Swapy and log swap events.

```html
<!DOCTYPE html>
<html>
<head>
  <style>
    .container { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
    .slot { min-height: 120px; border: 2px dashed #ccc; border-radius: 8px; }
    .item { background: #4CAF50; color: white; padding: 20px; border-radius: 6px; cursor: grab; }
    .item:active { cursor: grabbing; }
  </style>
</head>
<body>
  <div class="container" id="container">
    <div class="slot" data-swapy-slot="slot-1">
      <div class="item" data-swapy-item="item-a">Item A</div>
    </div>
    <div class="slot" data-swapy-slot="slot-2">
      <div class="item" data-swapy-item="item-b">Item B</div>
    </div>
    <div class="slot" data-swapy-slot="slot-3">
      <div class="item" data-swapy-item="item-c">Item C</div>
    </div>
  </div>

  <script type="module">
    import { createSwapy } from 'swapy';

    const container = document.querySelector('#container');
    const swapy = createSwapy(container);

    // Track swaps
    swapy.onSwap((event) => {
      console.log('Swapped:', event.draggingItem, 'from', event.fromSlot, 'to', event.toSlot);
      console.log('New layout:', event.newSlotItemMap.asObject);
    });
  </script>
</body>
</html>
```

--------------------------------

### React Integration with Swapy Hooks

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Shows how to integrate Swapy into a React application using the `useEffect` and `useRef` hooks. This example manages Swapy initialization, updates, and cleanup within the component lifecycle, and listens for swap events to update component state.

```jsx
import { useEffect, useRef, useState } from 'react';
import { createSwapy } from 'swapy';

function SwappableGrid() {
  const containerRef = useRef(null);
  const swapyRef = useRef(null);
  const [items, setItems] = useState([
    { id: 'item-1', content: 'Card 1', slot: 'slot-1' },
    { id: 'item-2', content: 'Card 2', slot: 'slot-2' },
    { id: 'item-3', content: 'Card 3', slot: 'slot-3' }
  ]);
  const [layout, setLayout] = useState([]);

  useEffect(() => {
    if (!containerRef.current) return;

    // Initialize Swapy
    const swapy = createSwapy(containerRef.current, {
      animation: 'spring',
      swapMode: 'hover'
    });

    // Update layout state on swap
    swapy.onSwap((event) => {
      setLayout(event.newSlotItemMap.asArray);
    });

    swapyRef.current = swapy;

    // Cleanup on unmount
    return () => {
      swapy.destroy();
    };
  }, []);

  // Update Swapy when items change
  useEffect(() => {
    if (swapyRef.current) {
      swapyRef.current.update();
    }
  }, [items]);

  const addItem = () => {
    const newId = `item-${items.length + 1}`;
    const newSlot = `slot-${items.length + 1}`;
    setItems([...items, { id: newId, content: `Card ${items.length + 1}`, slot: newSlot }]);
  };

  return (
    <div>
      <button onClick={addItem}>Add Item</button>
      <div ref={containerRef} className="grid">
        {items.map((item) => (
          <div key={item.id} data-swapy-slot={item.slot} className="slot">
            <div data-swapy-item={item.id} className="item">
              {item.content}
            </div>
          </div>
        ))}
      </div>
      <pre>Current Layout: {JSON.stringify(layout, null, 2)}</pre>
    </div>
  );
}

export default SwappableGrid;

```

--------------------------------

### Configure Swapy Options: Animation, Swap Mode, and Drag Constraints

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Explore various configuration options for Swapy, including animation styles, drag sensitivity, swap triggers, axis constraints, and manual control. This example demonstrates how to customize these settings during Swapy initialization and dynamically control dragging.

```javascript
import { createSwapy } from 'swapy';

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

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

  // Enable/disable dragging dynamically
  enabled: true,

  // Swap trigger: 'hover' (default) or 'drop'
  swapMode: 'drop',

  // Require press-and-hold before drag starts (adds delay)
  dragOnHold: true,

  // Auto-scroll container when dragging near edges
  autoScrollOnDrag: true,

  // Constrain drag direction: 'both' (default), 'x', or 'y'
  dragAxis: 'x',

  // Enable manual swap control via events
  manualSwap: false
});

// Dynamically enable/disable dragging
swapy.enable(false); // Disable
setTimeout(() => swapy.enable(true), 5000); // Re-enable after 5s

```

--------------------------------

### Swapy Drag Handles Configuration (HTML, CSS, JavaScript)

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Configure drag handles to restrict drag interaction to specific elements within items for Swapy. This example shows HTML structure with a drag handle element marked by `data-swapy-handle`. CSS is used to style the cursor for the drag handle. A minimal JavaScript snippet initializes Swapy and notes that dragging is only possible via the handle. This setup ensures that only designated elements initiate drag operations, improving user experience.

```html
<div class="container" id="container">
  <div class="slot" data-swapy-slot="slot-1">
    <div class="item" data-swapy-item="item-1">
      <!-- Only this handle can initiate drag -->
      <div class="drag-handle" data-swapy-handle>
        <svg width="20" height="20" viewBox="0 0 20 20">
          <circle cx="5" cy="5" r="2"/>
          <circle cx="15" cy="5" r="2"/>
          <circle cx="5" cy="15" r="2"/>
          <circle cx="15" cy="15" r="2"/>
        </svg>
      </div>
      <div class="content">
        <h3>Card Title</h3>
        <p>This text cannot be used to drag</p>
        <button data-swapy-no-drag>Click Me</button>
      </div>
    </div>
  </div>
</div>

<style>
  .drag-handle { cursor: grab; padding: 8px; }
  .drag-handle:active { cursor: grabbing; }
  .item { cursor: default; } /* Item itself is not draggable */
</style>

<script type="module">
  import { createSwapy } from 'swapy';
  const swapy = createSwapy(document.querySelector('#container'));
  // Items can only be dragged by the handle element
</script>
```

--------------------------------

### Vue 3 Integration with Swapy Composition API

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Provides an example of integrating Swapy into a Vue 3 application using the Composition API. It utilizes `ref`, `onMounted`, `onUnmounted`, and `watch` for Swapy instance management, event handling, and reactive updates based on item changes.

```vue
<template>
  <div>
    <button @click="addItem">Add Item</button>
    <div ref="containerRef" class="grid">
      <div
        v-for="item in items"
        :key="item.id"
        :data-swapy-slot="item.slot"
        class="slot"
      >
        <div :data-swapy-item="item.id" class="item">
          {{ item.content }}
        </div>
      </div>
    </div>
    <pre>{{ JSON.stringify(layout, null, 2) }}</pre>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue';
import { createSwapy } from 'swapy';

const containerRef = ref(null);
const swapyInstance = ref(null);
const items = ref([
  { id: 'item-1', content: 'Card 1', slot: 'slot-1' },
  { id: 'item-2', content: 'Card 2', slot: 'slot-2' },
  { id: 'item-3', content: 'Card 3', slot: 'slot-3' }
]);
const layout = ref([]);

onMounted(() => {
  const swapy = createSwapy(containerRef.value, {
    animation: 'dynamic',
    swapMode: 'hover'
  });

  swapy.onSwap((event) => {
    layout.value = event.newSlotItemMap.asArray;
  });

  swapyInstance.value = swapy;
});

onUnmounted(() => {
  if (swapyInstance.value) {
    swapyInstance.value.destroy();
  }
});

watch(items, () => {
  if (swapyInstance.value) {
    swapyInstance.value.update();
  }
}, { deep: true });

const addItem = () => {
  const newId = `item-${items.value.length + 1}`;
  const newSlot = `slot-${items.value.length + 1}`;
  items.value.push({
    id: newId,
    content: `Card ${items.value.length + 1}`,
    slot: newSlot
  });
};
</script>

<style scoped>
.grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
.slot { min-height: 120px; border: 2px dashed #ccc; }
.item { background: #4CAF50; color: white; padding: 20px; cursor: grab; }
</style>

```

--------------------------------

### Integrate Swapy with Custom Scroll Containers

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

This example demonstrates how to configure Swapy to work with a custom scrollable container. It shows how to find the closest scrollable parent and enable auto-scroll behavior while dragging items. Requires 'swapy' to be imported.

```html
<div id="scrollable-container" style="height: 400px; overflow-y: auto;">
  <div id="swapy-container">
    <!-- Slots and items here -->
  </div>
</div>

<script type="module">
  import { createSwapy, getClosestScrollableContainer } from 'swapy';

  const container = document.querySelector('#swapy-container');

  const swapy = createSwapy(container, {
    autoScrollOnDrag: true // Enable auto-scroll near edges
  });

  // Find the scrollable parent container
  const scrollContainer = getClosestScrollableContainer(container);
  console.log('Scrollable container:', scrollContainer);
  // Output: <div id="scrollable-container">...</div>

  // Manually control scroll behavior
  let isDragging = false;

  swapy.onSwapStart(() => {
    isDragging = true;
    scrollContainer.style.scrollBehavior = 'smooth';
  });

  swapy.onSwapEnd(() => {
    isDragging = false;
    scrollContainer.style.scrollBehavior = 'auto';
  });
</script>

```

--------------------------------

### Swapy Event Handlers for Swap Operations (JavaScript)

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Implement comprehensive lifecycle hooks for swap operations, including state tracking. This JavaScript code uses the 'swapy' library to listen for various events like before a swap begins, when a drag starts, when items swap positions, and when a drag ends. It allows for canceling swaps, logging swap details, persisting layout changes, and sending updates to a server. Dependencies include the 'swapy' library and standard browser APIs like localStorage and fetch.

```javascript
import { createSwapy } from 'swapy';

const swapy = createSwapy(document.querySelector('#container'));

// Called before swap begins - return false to cancel
swapy.onBeforeSwap((event) => {
  console.log('Attempting swap:', {
    from: event.fromSlot,
    to: event.toSlot,
    dragging: event.draggingItem,
    swapWith: event.swapWithItem
  });

  // Cancel swap if moving item-a to slot-3
  if (event.draggingItem === 'item-a' && event.toSlot === 'slot-3') {
    console.log('Swap blocked by validation');
    return false;
  }
  return true;
});

// Called when drag starts
swapy.onSwapStart((event) => {
  console.log('Drag started:', event.draggingItem, 'from', event.fromSlot);
  console.log('Initial layout:', event.slotItemMap.asObject);
});

// Called when items swap positions
swapy.onSwap((event) => {
  console.log('Swap completed:', {
    item: event.draggingItem,
    from: event.fromSlot,
    to: event.toSlot,
    swappedWith: event.swappedWithItem,
    oldLayout: event.oldSlotItemMap.asObject,
    newLayout: event.newSlotItemMap.asObject
  });

  // Persist layout to localStorage
  localStorage.setItem('layout', JSON.stringify(event.newSlotItemMap.asArray));
});

// Called when drag ends (dropped or canceled)
swapy.onSwapEnd((event) => {
  console.log('Drag ended. Changed:', event.hasChanged);
  console.log('Final layout:', event.slotItemMap.asObject);

  if (event.hasChanged) {
    // Send layout update to server
    fetch('/api/save-layout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(event.slotItemMap.asArray)
    });
  }
});
```

--------------------------------

### Integrate Swapy via CDN in HTML

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Include the Swapy UMD bundle directly in your HTML file using a CDN link. Access the library through the global `Swapy` namespace to create an instance.

```html
<script src="https://unpkg.com/swapy@1.0.3/dist/swapy.min.js"></script>
<script>
  // Access via global Swapy namespace
  const container = document.querySelector('#container');
  const swapy = Swapy.createSwapy(container, {
    animation: 'spring',
    swapMode: 'hover'
  });
</script>
```

--------------------------------

### Dynamic Content Updates with Swapy (JavaScript)

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Demonstrates how to dynamically add and remove items from a Swapy-managed interface using vanilla JavaScript. It covers initializing Swapy, updating its state after DOM modifications, and cleaning up resources.

```javascript
import { createSwapy } from 'swapy';

let swapy = createSwapy(document.querySelector('#container'));

// Add new slot and item dynamically
function addItem(slotId, itemId, content) {
  const container = document.querySelector('#container');

  const slot = document.createElement('div');
  slot.className = 'slot';
  slot.setAttribute('data-swapy-slot', slotId);

  const item = document.createElement('div');
  item.className = 'item';
  item.setAttribute('data-swapy-item', itemId);
  item.textContent = content;

  slot.appendChild(item);
  container.appendChild(slot);

  // Notify Swapy of DOM changes
  swapy.update();
}

// Remove item
function removeItem(itemId) {
  const item = document.querySelector(`[data-swapy-item="${itemId}"]`);
  if (item) {
    const slot = item.closest('[data-swapy-slot]');
    slot.remove();
    swapy.update();
  }
}

// Example usage
addItem('slot-4', 'item-d', 'New Item D');
setTimeout(() => removeItem('item-b'), 3000);

// Complete cleanup when removing Swapy
function cleanup() {
  swapy.destroy();
  swapy = null;
}
```

--------------------------------

### Manage Items Dynamically with Swapy

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

This snippet demonstrates how to dynamically add and remove items from a Swapy instance. It utilizes `initSlotItemMap`, `toSlottedItems`, and `dynamicSwapy` utilities to keep the Swapy instance in sync with changes in the data model. Ensure 'swapy' is imported.

```javascript
import { createSwapy, utils } from 'swapy';

// Your data model
const items = [
  { id: 'task-1', title: 'Design mockups', priority: 'high' },
  { id: 'task-2', title: 'Write tests', priority: 'medium' },
  { id: 'task-3', title: 'Deploy to staging', priority: 'low' }
];

// Initialize slot-item mapping
let slotItemMap = utils.initSlotItemMap(items, 'id');
console.log(slotItemMap);
// Output: [
//   { slot: '0', item: 'task-1' },
//   { slot: '1', item: 'task-2' },
//   { slot: '2', item: 'task-3' }
// ]

// Convert to ordered items based on slot positions
const slottedItems = utils.toSlottedItems(items, 'id', slotItemMap);
console.log(slottedItems);
// Output: [
//   { item: { id: 'task-1', title: 'Design mockups', ... }, slot: '0' },
//   { item: { id: 'task-2', title: 'Write tests', ... }, slot: '1' },
//   { item: { id: 'task-3', title: 'Deploy to staging', ... }, slot: '2' }
// ]

// Dynamically manage Swapy instance with item changes
const swapy = createSwapy(document.querySelector('#container'));

function updateItems(newItems) {
  utils.dynamicSwapy(
    swapy,
    newItems,
    'id',
    slotItemMap,
    (newMap) => { slotItemMap = newMap; },
    false // Set to true to only remove items without full update
  );
}

// Add new item
items.push({ id: 'task-4', title: 'Review PRs', priority: 'high' });
updateItems(items);

// Remove item
const filteredItems = items.filter(item => item.id !== 'task-2');
updateItems(filteredItems);

```

--------------------------------

### Swapy Slot-Item Map Access and Manipulation (JavaScript)

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Access and manipulate the current slot-item relationships in multiple formats using the 'swapy' library. This JavaScript code demonstrates how to retrieve the slot-item map as an object, a Map, or an array of objects, with the latter being suitable for serialization. It also shows how to restore a layout from saved state using localStorage and then updating the swapy instance. Dependencies include the 'swapy' library and the browser's localStorage API.

```javascript
import { createSwapy } from 'swapy';

const swapy = createSwapy(document.querySelector('#container'));

// Get current layout in different formats
const slotItemMap = swapy.slotItemMap();

// As object: { slotId: itemId }
console.log(slotItemMap.asObject);
// Output: { "slot-1": "item-a", "slot-2": "item-b", "slot-3": "item-c" }

// As Map
console.log(slotItemMap.asMap);
// Output: Map(3) { "slot-1" => "item-a", "slot-2" => "item-b", "slot-3" => "item-c" }

// As array of objects (best for serialization)
console.log(slotItemMap.asArray);
// Output: [
//   { slot: "slot-1", item: "item-a" },
//   { slot: "slot-2", item: "item-b" },
//   { slot: "slot-3", item: "item-c" }
// ]

// Restore layout from saved state
const savedLayout = localStorage.getItem('layout');
if (savedLayout) {
  const layout = JSON.parse(savedLayout);
  // Manually update DOM to match saved layout, then call:
  swapy.update();
}
```

--------------------------------

### Persist and Restore Swapy Layout with localStorage

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

This snippet shows how to save the Swapy layout to localStorage and restore it when the page loads. It also includes functionality to synchronize the layout across different browser tabs using the 'storage' event. Requires 'swapy' to be imported.

```javascript
import { createSwapy } from 'swapy';

const STORAGE_KEY = 'swapy-layout';

// Restore saved layout on initialization
function initializeWithSavedLayout() {
  const container = document.querySelector('#container');
  const savedLayout = localStorage.getItem(STORAGE_KEY);

  if (savedLayout) {
    const layout = JSON.parse(savedLayout);

    // Rearrange DOM to match saved layout
    layout.forEach(({ slot, item }) => {
      const slotEl = container.querySelector(`[data-swapy-slot="${slot}"]`);
      const itemEl = container.querySelector(`[data-swapy-item="${item}"]`);
      if (slotEl && itemEl) {
        slotEl.appendChild(itemEl);
      }
    });
  }

  // Initialize Swapy after DOM is arranged
  const swapy = createSwapy(container, {
    animation: 'spring'
  });

  // Save layout on every swap
  swapy.onSwap((event) => {
    localStorage.setItem(STORAGE_KEY, JSON.stringify(event.newSlotItemMap.asArray));
  });

  return swapy;
}

// Sync layout across multiple browser tabs
function syncLayoutAcrossTabs() {
  window.addEventListener('storage', (event) => {
    if (event.key === STORAGE_KEY && event.newValue) {
      const layout = JSON.parse(event.newValue);
      const container = document.querySelector('#container');

      // Update DOM to match new layout
      layout.forEach(({ slot, item }) => {
        const slotEl = container.querySelector(`[data-swapy-slot="${slot}"]`);
        const itemEl = container.querySelector(`[data-swapy-item="${item}"]`);
        if (slotEl && itemEl && !slotEl.contains(itemEl)) {
          slotEl.appendChild(itemEl);
        }
      });
    }
  });
}

const swapy = initializeWithSavedLayout();
syncLayoutAcrossTabs();

```

--------------------------------

### Conditional Swapping Logic with Swapy

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Implement business logic to validate and control swap operations using Swapy's `onBeforeSwap` event. This allows for defining rules for slots, such as whether they can receive or release items, and which items are allowed in specific slots. The `onSwap` event provides visual feedback for successful swaps.

```javascript
import { createSwapy } from 'swapy';

const swapy = createSwapy(document.querySelector('#container'));

// Define swap rules
const swapRules = {
  'locked-slot': {
    canReceive: false, // This slot cannot receive items
    canRelease: true   // But items can leave it
  },
  'vip-slot': {
    allowedItems: ['item-premium', 'item-vip'], // Only specific items allowed
    canReceive: true,
    canRelease: true
  }
};

swapy.onBeforeSwap((event) => {
  const toSlotRules = swapRules[event.toSlot];
  const fromSlotRules = swapRules[event.fromSlot];

  // Check if destination slot can receive items
  if (toSlotRules && !toSlotRules.canReceive) {
    console.log(`❌ ${event.toSlot} is locked and cannot receive items`);
    return false;
  }

  // Check if source slot can release items
  if (fromSlotRules && !fromSlotRules.canRelease) {
    console.log(`❌ ${event.fromSlot} is locked and cannot release items`);
    return false;
  }

  // Check if item is allowed in destination slot
  if (toSlotRules?.allowedItems && !toSlotRules.allowedItems.includes(event.draggingItem)) {
    console.log(`❌ ${event.draggingItem} is not allowed in ${event.toSlot}`);
    return false;
  }

  console.log(`✅ Swap allowed: ${event.draggingItem} → ${event.toSlot}`);
  return true;
});

// Visual feedback for validation
swapy.onSwap((event) => {
  const toSlot = document.querySelector(`[data-swapy-slot="${event.toSlot}"]`);
  toSlot.classList.add('swap-success');
  setTimeout(() => toSlot.classList.remove('swap-success'), 300);
});
```

--------------------------------

### TypeScript Integration with Swapy for Type Safety

Source: https://context7.com/context7/swapy_tahazsh/llms.txt

Leverage TypeScript for full type safety with Swapy. This includes type-safe configuration, event handlers, and API calls. Type inference simplifies working with event properties and ensures that data structures like `SlotItemMapArray` are used correctly.

```typescript
import {
  createSwapy,
  Swapy,
  SwapEvent,
  Config,
  SlotItemMapArray
} from 'swapy';

// Type-safe configuration
const config: Partial<Config> = {
  animation: 'spring',
  swapMode: 'drop',
  dragAxis: 'both',
  enabled: true,
  dragOnHold: false,
  autoScrollOnDrag: true,
  manualSwap: false
};

// Initialize with type checking
const container = document.querySelector<HTMLElement>('#container');
if (!container) throw new Error('Container not found');

const swapy: Swapy = createSwapy(container, config);

// Type-safe event handlers
swapy.onSwap((event: SwapEvent) => {
  const layout: SlotItemMapArray = event.newSlotItemMap.asArray;

  // Type inference works for event properties
  console.log({
    from: event.fromSlot,        // string
    to: event.toSlot,            // string
    item: event.draggingItem,    // string
    swapped: event.swappedWithItem, // string
    changed: event.hasChanged    // boolean
  });

  // Type-safe API call
  saveLayout(layout);
});

// Type-safe helper function
async function saveLayout(layout: SlotItemMapArray): Promise<void> {
  const response = await fetch('/api/layout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(layout)
  });

  if (!response.ok) {
    throw new Error('Failed to save layout');
  }
}

// Type-safe validation
swapy.onBeforeSwap((event) => {
  const isValid: boolean = validateSwap(event.draggingItem, event.toSlot);
  return isValid;
});

function validateSwap(itemId: string, slotId: string): boolean {
  // TypeScript ensures type safety
  return itemId.length > 0 && slotId.length > 0;
}
```
Tokens:
Raw