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.

<swappit-instance> is an HTML custom element that creates (or reinitializes) a Swappit instance using only HTML attributes — no JavaScript required. This makes it ideal for server-rendered templates, CMS-driven pages, and any situation where adding a <script> block feels unnecessarily heavy. You configure Swappit the same way you configure everything else in your HTML: with attributes.

​
Basic usage

The only required attribute is data-handle. This single line creates a fully functional Swappit instance: 
<swappit-instance data-handle="my-app"></swappit-instance>
All other attributes are optional and default to their off states. Place the element anywhere in <body> — after the Swappit script tag.
The swappit.min.js <script> tag must be present in the page — typically at the end of <body>. If the browser parses <swappit-instance> before the script has loaded, it queues the element for upgrade; connectedCallback fires once the script runs and registers the custom element. A safe pattern is to place <swappit-instance> anywhere in <body> and put <script src="swappit.min.js"> at the very end of the body.

​
Available attributes

AttributeTypeDescriptionDefault
data-handlestringInstance handle — must be unique (required)—
data-logpresence booleanEnables color-coded console loggingfalse
data-update-urlpresence booleanUpdates the browser URL bar on each navigationfalse
data-enable-historypresence booleanEnables back/forward browser navigationfalse
data-preloadstringDefault preload mode for managed links: "hover" or "instant"false
Presence booleans are activated simply by including the attribute — no value needed. Omitting the attribute is equivalent to false: 
<!-- log is ON -->
<swappit-instance data-handle="my-app" data-log></swappit-instance>

<!-- log is OFF (attribute absent) -->
<swappit-instance data-handle="my-app"></swappit-instance>
data-enable-history requires data-update-url to have any effect. Without URL updates, Swappit has no URL to push to the browser history stack, so the popstate listener is never registered. If you include data-enable-history without data-update-url, Swappit will log a warning and history navigation will not work.

​
Behavior

When the custom element connects to the DOM, it checks the Swappit.instances registry:
1

No existing instance

If no instance with the given data-handle exists, <swappit-instance> creates a new Swappit instance using the attribute values as options.
2

Instance already exists

If an instance with that handle is already registered, <swappit-instance> calls reinit() on it with the new attribute values — merging the new options into the existing instance without destroying it. This lets you re-configure a running instance declaratively, for example after a server-side template re-renders the element with different attributes.

​
Full example

A complete HTML page combining update regions, declarative configuration, navigation links, and a JavaScript block that accesses the instance and listens to events: 
<!-- Update regions -->
<div data-my-app-update="header"><h1>Home</h1></div>
<div data-my-app-update="content"><p>Home content</p></div>

<!-- Declarative instance — all options configured in HTML -->
<swappit-instance
  data-handle="my-app"
  data-log
  data-update-url
  data-enable-history
  data-preload="hover">
</swappit-instance>

<!-- Navigation links -->
<a href="./about.html" data-swappit-handle="my-app">About</a>
<a href="./contact.html" data-swappit-handle="my-app" data-preload="instant">Contact</a>

<script src="https://cdn.jsdelivr.net/npm/@soyleninjs/swappit/swappit.min.js"></script>
<script>
  // Access the instance created by the element
  const myApp = Swappit.instances.get('my-app');

  window.addEventListener('swappit:my-app:update:after', (e) => {
    console.log('Updated from:', e.detail.url);
  });
</script>
The recommended body layout is:
  1. Your update region elements
  2. Your <swappit-instance> element and navigation links
  3. <script src="swappit.min.js"> — this defines Swappit, registers <swappit-instance>, and triggers the upgrade of any already-parsed <swappit-instance> elements
  4. Any additional inline <script> blocks that use Swappit.instances.get()

Build docs developers (and LLMs) love

Get started for freeTalk to us