Document swapFunctions of astro:transitions/client

src/content/docs/en/guides/view-transitions.mdx

@@ -642,6 +642,36 @@ At this point of the lifecycle, you could choose to define your own swap impleme
 </script>
 ```
 
+#### Building a custom swap function
+
+<p><Since v="4.15.0" /></p>
+
+The `swapFunction` object of the `astro:transitions/client` module provides five utility functions that handle specific swap-related tasks, including handling document attributes, page elements, and script execution. These functions can be used directly to define a custom swap implementation.
+
+The following example demonstrates how to use these functions to recreate Astro's built-in swap implementation:
+
+```astro
+<script>
+import { swapFunctions } from 'astro:transitions/client';
+
+// substitutes window.document with doc
+function mySwap(doc: Document) {
+  swapFunctions.deselectScripts(doc);
+  swapFunctions.swapRootAttributes(doc);
+  swapFunctions.swapHeadElements(doc);
+  const restoreFocusFunction = swapFunctions.saveFocus();
+  swapFunctions.swapBodyElement(doc.body, document.body);
+  restoreFocusFunction();
+};
+
+...
+  ev.swap = () => mySwap(ev.newDocument);
+...
+<script>
+```
+Custom swap implementations can start with this template and add or replace individual steps with custom logic as needed.
+
+
 ### `astro:after-swap`
 
 An event that fires immediately after the new page replaces the old page. You can listen to this event on the `document` and trigger actions that will occur before the new page's DOM elements render and scripts run.