> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wsx.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Swaps

> Understanding content swapping strategies in WSX

# 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:

```html theme={null}
<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:

```html theme={null}
<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:

```html theme={null}
<div id="content">Original text</div>

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

## Positional Swaps

### beforebegin

Insert before the element:

```html theme={null}
<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:

```html theme={null}
<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:

```html theme={null}
<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:

```html theme={null}
<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:

```html theme={null}
<!-- 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:

```javascript theme={null}
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:

```html theme={null}
<!-- 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:

```html theme={null}
<!-- 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

```javascript theme={null}
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

```html theme={null}
<!-- 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

```html theme={null}
<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

```html theme={null}
<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:

```html theme={null}
<!-- 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

```javascript theme={null}
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

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

## Next Steps

* Learn about [Out-of-Band Updates](/concepts/oob-updates) for multiple element updates
* Explore [Client Events](/client/events) for swap event handling
* Understand [Server Broadcasting](/server/broadcasting) for coordinated updates