Swaps

Swaps define how new content replaces or is inserted into existing DOM elements. WSX provides flexible swap strategies with timing and animation controls.

Basic Swap Types

innerHTML (Default)

Replace the content inside an element:

<div id="content">
  <p>Original content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: <div id="content"><p>New content</p></div> -->

outerHTML

Replace the entire element:

<div id="content">
  <p>Original content</p>
</div>

<!-- Server returns: <section id="content"><p>New content</p></section> -->
<!-- Result: <section id="content"><p>New content</p></section> -->

Text Content

Replace only the text content:

<div id="content">Original text</div>

<!-- Server returns: "New text" -->
<!-- Result: <div id="content">New text</div> -->

Positional Swaps

beforebegin

Insert before the element:

<div id="target">Existing content</div>

<!-- Server returns: <div>New content</div> -->
<!-- Result: 
<div>New content</div>
<div id="target">Existing content</div>
-->

afterbegin

Insert at the beginning of the element:

<div id="target">
  <p>Existing content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: 
<div id="target">
  <p>New content</p>
  <p>Existing content</p>
</div>
-->

beforeend

Insert at the end of the element:

<div id="target">
  <p>Existing content</p>
</div>

<!-- Server returns: <p>New content</p> -->
<!-- Result: 
<div id="target">
  <p>Existing content</p>
  <p>New content</p>
</div>
-->

afterend

Insert after the element:

<div id="target">Existing content</div>

<!-- Server returns: <div>New content</div> -->
<!-- Result: 
<div id="target">Existing content</div>
<div>New content</div>
-->

Swap Specifications

Client-Side Specification

Use wx-swap attribute to specify swap behavior:

<!-- Replace innerHTML -->
<div wx-swap="innerHTML">Content</div>

<!-- Replace outerHTML -->
<div wx-swap="outerHTML">Content</div>

<!-- Insert at beginning -->
<div wx-swap="afterbegin">Content</div>

<!-- Insert at end -->
<div wx-swap="beforeend">Content</div>

Server-Side Specification

Specify swap in the response:

wsx.on("my-action", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML"  // Override client-side swap
  };
});

Timing Modifiers

Swap Timing

Control when the swap occurs:

<!-- Immediate swap -->
<div wx-swap="innerHTML">Content</div>

<!-- 300ms delay before swap -->
<div wx-swap="innerHTML swap:300ms">Content</div>

<!-- 1 second delay -->
<div wx-swap="innerHTML swap:1s">Content</div>

Settle Timing

Control when animations settle:

<!-- 100ms settle time -->
<div wx-swap="innerHTML settle:100ms">Content</div>

<!-- Combined timing -->
<div wx-swap="innerHTML swap:300ms settle:100ms">Content</div>

Server-Side Timing

wsx.on("animated-update", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML swap:300ms settle:100ms"
  };
});

Animation and Effects

Fade Effects

<!-- Fade in new content -->
<div wx-swap="innerHTML swap:300ms settle:100ms">Content</div>

<style>
  .wsx-settling {
    opacity: 0;
    transition: opacity 300ms ease;
  }
  
  .wsx-settled {
    opacity: 1;
  }
</style>

Slide Effects

<div wx-swap="innerHTML swap:300ms settle:200ms">Content</div>

<style>
  .wsx-settling {
    transform: translateX(-100%);
    transition: transform 300ms ease;
  }
  
  .wsx-settled {
    transform: translateX(0);
  }
</style>

Custom Animations

<div wx-swap="innerHTML swap:500ms settle:200ms">Content</div>

<style>
  .wsx-settling {
    transform: scale(0.8);
    opacity: 0;
    transition: all 500ms cubic-bezier(0.4, 0, 0.2, 1);
  }
  
  .wsx-settled {
    transform: scale(1);
    opacity: 1;
  }
</style>

Scroll Behavior

Auto-Scroll

Control scrolling after swaps:

<!-- Scroll to top -->
<div wx-swap="innerHTML show:top">Content</div>

<!-- Scroll to bottom -->
<div wx-swap="innerHTML show:bottom">Content</div>

<!-- Scroll to element -->
<div wx-swap="innerHTML show:window">Content</div>

<!-- Smooth scrolling -->
<div wx-swap="innerHTML show:top scroll:smooth">Content</div>

Server-Side Scroll Control

wsx.on("scroll-action", async (request, connection) => {
  return {
    id: request.id,
    target: request.target,
    html: `<div>New content</div>`,
    swap: "innerHTML show:top scroll:smooth"
  };
});

Best Practices

Choose Appropriate Swap Types: Use the right swap for your use case
Add Smooth Transitions: Use timing modifiers for better UX
Handle Scroll Behavior: Control scrolling for long content
Clean Up Resources: Handle cleanup before swaps
Test Animations: Ensure animations work across browsers
Consider Performance: Avoid expensive animations on slow devices

Next Steps

Learn about Out-of-Band Updates for multiple element updates
Explore Client Events for swap event handling
Understand Server Broadcasting for coordinated updates

Get Started

Core Concepts

Client Guide

Server Guide

Framework Integration

Swaps

Swaps

Basic Swap Types

innerHTML (Default)

outerHTML

Text Content

Positional Swaps

beforebegin

afterbegin

beforeend

afterend

Swap Specifications

Client-Side Specification

Server-Side Specification

Timing Modifiers

Swap Timing

Settle Timing

Server-Side Timing

Animation and Effects

Fade Effects

Slide Effects

Custom Animations

Scroll Behavior

Auto-Scroll

Server-Side Scroll Control

Best Practices

Next Steps

​Swaps

​Basic Swap Types

​innerHTML (Default)

​outerHTML

​Text Content

​Positional Swaps

​beforebegin

​afterbegin

​beforeend

​afterend

​Swap Specifications

​Client-Side Specification

​Server-Side Specification

​Timing Modifiers

​Swap Timing

​Settle Timing

​Server-Side Timing

​Animation and Effects

​Fade Effects

​Slide Effects

​Custom Animations

​Scroll Behavior

​Auto-Scroll

​Server-Side Scroll Control

​Best Practices

​Next Steps

Swaps

Basic Swap Types

innerHTML (Default)

outerHTML

Text Content

Positional Swaps

beforebegin

afterbegin

beforeend

afterend

Swap Specifications

Client-Side Specification

Server-Side Specification

Timing Modifiers

Swap Timing

Settle Timing

Server-Side Timing

Animation and Effects

Fade Effects

Slide Effects

Custom Animations

Scroll Behavior

Auto-Scroll

Server-Side Scroll Control

Best Practices

Next Steps