Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/soyleninjs/swappit/llms.txt

Use this file to discover all available pages before exploring further.

If something isn’t working as expected, the first step is to enable log: true on your instance. Swappit’s colorized console output shows exactly what it is doing at each step — successful fetches, DOM updates, warnings about duplicate regions, and errors with their full messages. 
const app = new Swappit('app', { log: true });
The most common cause is a mismatch between the data-[handle]-update attribute names on the source page and the target page, or a different handle string.Checklist:
  • The handle passed to new Swappit('handle') must exactly match the prefix in your data attributes.
  • data-app-update="content" on the source page requires data-app-update="content" (same name) on the target page.
  • Names are case-sensitive — Content ≠ content.
<!-- Source page -->
<div data-app-update="content">Original</div>

<!-- Target page — name must match exactly -->
<div data-app-update="content">Updated</div>
Swappit only accepts relative URLs that begin with / or ./. Any other format throws an error.
// ✅ Valid
app.update('/about.html');
app.update('./about.html');

// ❌ Invalid — throws error
app.update('about.html');           // Missing leading / or ./
app.update('https://example.com'); // External URL not allowed
app.update('../parent.html');      // ../ prefix not allowed
Check the href values of your links as well — the same rule applies to href attributes on elements with data-swappit-handle.
If updated regions appear to render in the wrong sequence, use the data-[handle]-update-order attribute with numeric values. Elements with this attribute are processed first (lowest to highest); elements without it are processed last.
<div data-app-update="section1" data-app-update-order="2">Section 1</div>
<div data-app-update="section2" data-app-update-order="1">Section 2</div>
<div data-app-update="section3">Section 3 (last)</div>
Execution order: section2 → section1 → section3.
Each handle string must be unique across all active instances. Passing the same handle to new Swappit() twice throws this error.
// ❌ Throws: handle "app" already in use
const app1 = new Swappit('app');
const app2 = new Swappit('app');
To retrieve an existing instance instead of creating a new one:
const app = Swappit.instances.get('app');
Alternatively, use the <swappit-instance> custom element — it automatically calls reinit() if an instance with that handle already exists, instead of throwing.
Back and forward buttons only work when both updateUrl: true and enableHistory: true are set. One without the other is not enough.
// ❌ enableHistory alone has no effect
const app = new Swappit('app', { enableHistory: true });

// ✅ Both required
const app = new Swappit('app', {
  updateUrl: true,
  enableHistory: true
});
With only updateUrl: true (no enableHistory), the URL updates on each swap using replaceState but the history stack is not extended.
Only one Swappit instance may have both updateUrl: true and enableHistory: true active at the same time. A second instance with the same combination throws this error.
// ❌ Second instance throws
const app1 = new Swappit('app1', { updateUrl: true, enableHistory: true });
const app2 = new Swappit('app2', { updateUrl: true, enableHistory: true }); // Error!
Fix: Give only one instance full history control. Other instances can use updateUrl: true (without enableHistory) if they need URL updates, or omit both options entirely.
The data-preload attribute (and the preload option) only recognize the exact string values "instant" and "hover". Any other value — including an empty string or a typo — is silently treated as no preload.
<!-- ✅ Valid values -->
<a href="./page.html" data-swappit-handle="app" data-preload="instant">Instant</a>
<a href="./page.html" data-swappit-handle="app" data-preload="hover">Hover</a>

<!-- ❌ Silently ignored -->
<a href="./page.html" data-swappit-handle="app" data-preload="Hover">Wrong case</a>
<a href="./page.html" data-swappit-handle="app" data-preload="auto">Unknown value</a>
Scripts inside swapped regions do not execute automatically — this is intentional. Use the static helper methods in the update:after event to re-run them explicitly.
window.addEventListener('swappit:app:update:after', () => {
  // Re-run inline scripts
  const inlineScripts = document.querySelectorAll('[data-app-update] script:not([src])');
  if (inlineScripts.length > 0) {
    Swappit.updateScriptByContent(Array.from(inlineScripts));
  }

  // Reload an external script by partial src match
  Swappit.updateScriptBySrc('my-widget.js');
});
See the Script Handling guide for a full explanation.
By default, update() serves the URL from cache if it has been fetched before. Pass false as the second argument to force a fresh download:
app.update('./page.html', false); // Bypass cache
You can also set this per link in HTML:
<a href="./page.html" data-swappit-handle="app" data-use-cache="false">Always Fresh</a>
The <swappit-instance> custom element requires a non-empty data-handle attribute. Without it, the element logs an error and does nothing.
<!-- ❌ Missing data-handle — no instance is created -->
<swappit-instance></swappit-instance>

<!-- ✅ Correct -->
<swappit-instance data-handle="app"></swappit-instance>
Also make sure the swappit.min.js script is loaded — the custom element is defined inside it.
Verify the event name follows the exact format: swappit:[handle]:[event].
// ✅ Correct format
window.addEventListener('swappit:app:update:after', handler);
window.addEventListener('swappit:app:update:before', handler);
window.addEventListener('swappit:app:update:error', handler);
window.addEventListener('swappit:app:historyUpdate:before', handler);
window.addEventListener('swappit:app:historyUpdate:after', handler);
window.addEventListener('swappit:app:historyUpdate:error', handler);
window.addEventListener('swappit:app:reinit', handler);
window.addEventListener('swappit:app:destroy', handler);

// ❌ Wrong — will never fire
window.addEventListener('swappit:update:after', handler);     // Missing handle
window.addEventListener('swappit:app:updated', handler);      // Wrong event name
Replace app with your actual instance handle. All events are dispatched on window.

Build docs developers (and LLMs) love

Get started for freeTalk to us