### Install Swup Head Plugin (JavaScript) Source: https://github.com/swup/head-plugin/blob/main/README.md Demonstrates installation of the Swup Head Plugin using npm and importing it into a JavaScript bundle. ```bash npm install @swup/head-plugin ``` ```javascript import SwupHeadPlugin from '@swup/head-plugin'; ``` -------------------------------- ### Complete Configuration Example — JavaScript (Swup Head Plugin) Source: https://context7.com/swup/head-plugin/llms.txt Comprehensive configuration for advanced control of head management. Persist third-party tags (e.g., analytics), wait for new stylesheets before showing content with a timeout, and synchronize specific attributes (language, direction, theme, data-page-*). Demonstrates real-world navigation and expected outcomes. ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; const swup = new Swup({ plugins: [ new SwupHeadPlugin({ // Persist third-party scripts and analytics persistTags: (tag) => { const keepSelectors = [ 'script[data-analytics]', 'script[src*="gtag"]', 'link[data-external-theme]' ]; return keepSelectors.some(selector => tag.matches(selector)); }, // Wait for new stylesheets before showing content awaitAssets: true, timeout: 5000, // Update language, direction, theme, and all data attributes attributes: ['lang', 'dir', 'class', /^data-theme/, /^data-page-/] }) ] }); // Example page transition scenario: // User navigates from /home to /about // // Before (home page): // // // // // // // After (about page): // // // // // // // // Result: // - /home.css removed, /about.css added // - gtag.js persisted (not removed/re-added) // - data-page-type updated to "standard" // - Transition waits for about.css to load ``` -------------------------------- ### Initialize Swup Head Plugin with default options Source: https://context7.com/swup/head-plugin/llms.txt Demonstrates basic setup of Swup with the Head Plugin added to the plugins array. The plugin automatically updates head contents on each transition, handling removal of orphaned tags and updating language attributes. No additional configuration is required for standard usage. ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // Basic initialization with default options const swup = new Swup({ plugins: [new SwupHeadPlugin()] }); // The plugin will automatically update head contents on every page transition // Default behavior: removes orphaned tags, adds new tags, updates lang and dir attributes ``` -------------------------------- ### Initialize Swup with Head Plugin Source: https://github.com/swup/head-plugin/blob/main/README.md Shows how to initialize the Swup object and include the SwupHeadPlugin. ```javascript const swup = new Swup({ plugins: [new SwupHeadPlugin()] }); ``` -------------------------------- ### Configure Swup Head Plugin - awaitAssets Source: https://github.com/swup/head-plugin/blob/main/README.md Shows how to use the `awaitAssets` option to ensure stylesheets are loaded before transition. ```javascript new SwupHeadPlugin({ awaitAssets: true }); ``` -------------------------------- ### Await asset loading before transition with Swup Head Plugin Source: https://context7.com/swup/head-plugin/llms.txt Configures the plugin to delay the completion of a page transition until newly added stylesheets have loaded, mitigating flash‑of‑unstyled‑content issues. A timeout ensures the transition proceeds even if assets fail to load within the specified period. ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // Wait for all new stylesheets to load before showing new content const swup = new Swup({ plugins: [ new SwupHeadPlugin({ awaitAssets: true, timeout: 3000 // Continue after 3 seconds even if assets haven't loaded }) ] }); ``` -------------------------------- ### Configure Swup Head Plugin - persistAssets Source: https://github.com/swup/head-plugin/blob/main/README.md Illustrates the use of the `persistAssets` option to preserve orphaned assets. ```javascript new SwupHeadPlugin({ persistAssets: true }); ``` -------------------------------- ### waitForAssets — JavaScript (Swup Head Plugin) Source: https://context7.com/swup/head-plugin/llms.txt Creates promises that resolve when newly added elements finish loading, with an optional timeout. Scripts are ignored. Intended to be used by the plugin when awaitAssets is enabled to prevent layout shift and ensure styles are applied before content is shown. ```javascript import waitForAssets from '@swup/head-plugin/src/waitForAssets'; // Wait for multiple stylesheets to load const newElements = [ Object.assign(document.createElement('link'), { rel: 'stylesheet', href: '/css/theme.css' }), Object.assign(document.createElement('link'), { rel: 'stylesheet', href: '/css/components.css' }), Object.assign(document.createElement('script'), { src: '/js/app.js' }) ]; // Add elements to document newElements.forEach(el => document.head.appendChild(el)); // Wait for stylesheets (scripts are ignored) const loadPromises = waitForAssets(newElements, 3000); console.log(`Waiting for ${loadPromises.length} stylesheets`); // 2 Promise.all(loadPromises).then(() => { console.log('All stylesheets loaded or timed out after 3000ms'); // Safe to show content now - styles are applied }); ``` -------------------------------- ### Configure Swup Head Plugin - persistTags Source: https://github.com/swup/head-plugin/blob/main/README.md Demonstrates customizing the `persistTags` option to selectively preserve tags. ```javascript new SwupHeadPlugin({ // Keep all orphaned tags persistTags: true, // Keep all tags that match a CSS selector persistTags: 'style[data-keep-style]', // Use a function to determine whether to keep a tag persistTags: (tag) => tag.children.length > 1 }); ``` -------------------------------- ### Configure Swup Head Plugin - attributes Source: https://github.com/swup/head-plugin/blob/main/README.md Demonstrates customizing the attributes to update on the html element. ```javascript { attributes: ['lang', 'dir', 'style', /^data-/] } ``` -------------------------------- ### Configure asset persistence in Swup Head Plugin Source: https://context7.com/swup/head-plugin/llms.txt Shows three ways to keep specific head assets across page transitions: persisting all assets, using a CSS selector string, or providing a custom function for fine‑grained control. These configurations prevent removal of essential scripts or styles that should survive navigation. ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // Persist all link, script, and style tags const swup = new Swup({ plugins: [ new SwupHeadPlugin({ persistAssets: true }) ] }); ``` ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // persistence with CSS selector const swupWithCustomPersist = new Swup({ plugins: [ new SwupHeadPlugin({ persistTags: 'style[data-keep], script[data-analytics]' }) ] }); ``` ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // Function-based tag persistence with custom logic const swupWithFunction = new Swup({ plugins: [ new SwupHeadPlugin({ persistTags: (tag) => { // Keep all tags with data-persist attribute if (tag.hasAttribute('data-persist')) return true; // Keep specific analytics scripts if (tag.matches('script[src*="analytics.js"]')) return true; return false; } }) ] }); ``` -------------------------------- ### Update HTML element attributes during transitions with Swup Head Plugin Source: https://context7.com/swup/head-plugin/llms.txt Demonstrates syncing HTML element attributes such as lang, dir, class, and any data‑* attributes from the incoming page. The configuration accepts both literal attribute names and regular expressions for pattern matching. ```javascript import Swup from 'swup'; import SwupHeadPlugin from '@swup/head-plugin'; // Update multiple attributes including data attributes const swup = new Swup({ plugins: [ new SwupHeadPlugin({ attributes: ['lang', 'dir', 'class', /^data-/] }) ] }); ``` -------------------------------- ### mergeHeadContents — JavaScript (Swup Head Plugin) Source: https://context7.com/swup/head-plugin/llms.txt Synchronizes contents between documents by computing differences and returning tags to remove and tags to add. Supports persistence rules (e.g., keep analytics scripts). Designed to be used internally by the Swup Head Plugin but can be called directly for manual head merging. ```javascript import mergeHeadContents from '@swup/head-plugin/src/mergeHeadContents'; // Manual head merging (typically handled internally by the plugin) const currentHead = document.head; const newDocument = new DOMParser().parseFromString( ` `, 'text/html' ); const { removed, added } = mergeHeadContents( currentHead, newDocument.head, { shouldPersist: (el) => { // Keep analytics scripts across page transitions return el.matches('script[data-analytics]'); } } ); console.log(`Removed ${removed.length} tags`); // Tags from old page not in new page console.log(`Added ${added.length} tags`); // Tags from new page not in old page // Function clones new elements and inserts them while removing orphaned ones ``` -------------------------------- ### updateAttributes — JavaScript (Swup Head Plugin) Source: https://context7.com/swup/head-plugin/llms.txt Copies attributes from a source element to a target element, adding new attributes and removing obsolete ones based on a whitelist of names or regex patterns. Useful for synchronizing language, direction, and data attributes on or other root elements during navigation. ```javascript import updateAttributes from '@swup/head-plugin/src/updateAttributes'; // Synchronize specific attributes between two elements const currentHtml = document.documentElement; const newHtml = new DOMParser().parseFromString( '', 'text/html' ).documentElement; // Update only language and data attributes updateAttributes(currentHtml, newHtml, ['lang', /^data-/]); // Result: currentHtml now has lang="es" and all data-* attributes from newHtml // Other attributes remain unchanged, missing attributes are removed console.log(currentHtml.getAttribute('lang')); // "es" console.log(currentHtml.getAttribute('data-theme')); // "dark" console.log(currentHtml.getAttribute('data-version')); // "2.0" ``` === COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.