Swup Head Plugin

https://github.com/swup/head-plugin
Admin
Swup Head Plugin is a swup plugin that updates the document <head> during page transitions—adding...
Tokens:17,684
Snippets:134
Trust Score:7.2
License:MIT
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Install and import @swup/head-plugin

Source: https://github.com/swup/head-plugin/blob/main/README.md

Install the plugin from npm and import it into your bundle.

```bash
npm install @swup/head-plugin
```

```js
import SwupHeadPlugin from '@swup/head-plugin';
```

--------------------------------

### Usage example for SwupHeadPlugin

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/configuration.md

Usage example showing how to instantiate SwupHeadPlugin with constructor options. The plugin is configured entirely through the constructor options object; there are no config files or environment variables.

```js
import Swup from 'swup';
import SwupHeadPlugin from '@swup/head-plugin';

const swup = new Swup({
  plugins: [
    new SwupHeadPlugin({
      persistTags: 'style[data-keep], script[data-init]',
      awaitAssets: true,
      attributes: ['lang', 'dir', /^data-/],
      timeout: 5000
    })
  ]
});
```

--------------------------------

### SwupHeadPlugin Constructor

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Documentation for the SwupHeadPlugin constructor, including parameters, behavior, and usage examples.

```APIDOC
## Constructor

```ts
constructor(options: Partial<Options> = {}) {
	super();

	this.options = { ...this.defaults, ...options };

	// persistAssets is a shortcut for: persistTags with a default asset selector for scripts & styles
	if (this.options.persistAssets && !this.options.persistTags) {
		this.options.persistTags = 'link[rel=stylesheet], script[src], style';
	}
}
```

Source: `src/index.ts:35-44`.

### Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| options | `Partial<Options>` | No | `{}` | Partial configuration merged over the `defaults` object. See [configuration.md](../configuration.md) for every key. |

`Options` (module-internal type, see [types.md](../types.md)):

```ts
type Options = {
	persistAssets: boolean;
	persistTags: boolean | string | ((el: Element) => boolean);
	awaitAssets: boolean;
	attributes: (string | RegExp)[];
	timeout: number;
};
```

### Behavior

1. Calls `super()` to initialize the `Plugin` base class.
2. Merges `options` over `this.defaults` into `this.options`.
3. Shortcut: if `persistAssets: true` was passed and `persistTags` was not set (i.e. still falsy), `persistTags` is rewritten to the selector string `'link[rel=stylesheet], script[src], style'`. This means the empty-string `''` value for `persistTags` is treated as "not set" and will be replaced by the shortcut (relevant since `persistTags` is checked with `if (persistTags.length > 0)` at runtime in `isPersistentTag`).

### Examples

Basic initialization in a swup application:

```js
import Swup from 'swup';
import SwupHeadPlugin from '@swup/head-plugin';

const swup = new Swup({
  plugins: [
    new SwupHeadPlugin()
  ]
});
```

Initialization with options — keep a third-party style tag, wait for new stylesheets, and track custom `data-*` attributes on `<html>`:

```js
const swup = new Swup({
  plugins: [
    new SwupHeadPlugin({
      persistTags: 'style[data-keep]',
      awaitAssets: true,
      attributes: ['lang', 'dir', /^data-/],
      timeout: 5000
    })
  ]
});
```

Note: instantiating the plugin without mounting it on a swup instance is safe (the constructor performs no DOM or swup access); the plugin only interacts with swup once `use()`d (which calls `mount()`).
```

--------------------------------

### Using waitForAssets to await stylesheet loading

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Usage example for the internal module. Collects all stylesheet links, calls waitForAssets with a 3000 ms timeout, and awaits all promises before logging. Note the module is not part of the public API; import it directly from the source file.

```js
import waitForAssets from './waitForAssets.js'; // internal module

const addedLinks = [...document.querySelectorAll('link[rel=stylesheet]')];
const promises = waitForAssets(addedLinks, 3000);

if (promises.length) {
  await Promise.all(promises);
  console.log('All new stylesheets are loaded');
}
```

--------------------------------

### Default shouldPersist usage

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Example using the default shouldPersist (persist nothing). All orphaned tags are removed except those excluded by shouldManageTag (title and [data-swup-theme]).

```js
const currentHead = document.head;
const { head: newHead } = new DOMParser().parseFromString('<html><head></head><body></body></html>', 'text/html');

// Empty the head of everything except <title> and [data-swup-theme] elements
mergeHeadContents(currentHead, newHead);
```

--------------------------------

### No filter - full attribute synchronization

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/updateAttributes.md

Example showing updateAttributes without a filter, which copies all attributes from the source and removes attributes on the target that are not present on the source.

```JavaScript
const current = document.querySelector('#el');
const { documentElement: incoming } = new DOMParser().parseFromString(
  '<html id="next" data-state="ready"><head></head><body></body></html>',
  'text/html'
);

updateAttributes(current, incoming); // copies id/data-state, removes attributes not on source
```

--------------------------------

### Direct use of mergeHeadContents with shouldPersist

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Direct usage example showing how to call mergeHeadContents with a custom shouldPersist predicate. Parses a new HTML document, merges its head into the current document, and logs the counts of removed and added elements.

```js
import mergeHeadContents from './mergeHeadContents.js'; // internal module

const currentHead = document.head;
const { head: newHead } = new DOMParser().parseFromString(
  '<html><head><meta name="viewport" content="width=device-width"></head></body></html>',
  'text/html'
);

// Replace the live head contents, keeping any style tag with data-keep
const { removed, added } = mergeHeadContents(currentHead, newHead, {
  shouldPersist: (el) => el.matches('style[data-keep]')
});

console.log(`Removed ${removed.length}, added ${added.length}`); // e.g. "Removed 2, added 1"
console.log(added[0].isConnected); // true — inserted into the live document
```

--------------------------------

### Basic usage - sync lang attribute

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/updateAttributes.md

Example showing how to use updateAttributes to sync the 'lang' attribute between two HTML elements. It imports the internal module, creates a new document from a string, and calls updateAttributes with a filter for 'lang'.

```JavaScript
import updateAttributes from './updateAttributes.js'; // internal module

const current = document.documentElement;
const { documentElement: incoming } = new DOMParser().parseFromString(
  '<html lang="de"><head></head><body></body></html>',
  'text/html'
);

updateAttributes(current, incoming, ['lang']);
console.log(document.documentElement.lang); // 'de'
```

--------------------------------

### Using isPersistentTag with persistTags option

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Example usage of `isPersistentTag` with a CSS selector option. Creates a plugin with `persistTags: 'style[data-keep]'` and checks each style tag, logging a message for those that will persist.

```js
const plugin = new SwupHeadPlugin({ persistTags: 'style[data-keep]' });

document.querySelectorAll('style').forEach((style) => {
  if (plugin.isPersistentTag(style)) {
    console.log('This style tag will survive transitions');
  }
});
```

--------------------------------

### SwupHeadPlugin initialization with options

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Initialization with options: keeps a third-party style tag via persistTags, waits for new stylesheets with awaitAssets, tracks custom data-* attributes on <html>, and sets a 5000ms timeout.

```js
const swup = new Swup({
  plugins: [
    new SwupHeadPlugin({
      persistTags: 'style[data-keep]',
      awaitAssets: true,
      attributes: ['lang', 'dir', /^data-/],
      timeout: 5000
    })
  ]
});
```

--------------------------------

### Initialize Swup with SwupHeadPlugin

Source: https://github.com/swup/head-plugin/blob/main/README.md

To run this plugin, include an instance in the swup options.

```javascript
const swup = new Swup({
  plugins: [new SwupHeadPlugin()]
});
```

--------------------------------

### Include @swup/head-plugin from CDN

Source: https://github.com/swup/head-plugin/blob/main/README.md

Include the minified production file from a CDN.

```html
<script src="https://unpkg.com/@swup/head-plugin@2"></script>
```

--------------------------------

### Register SwupHeadPlugin with Swup

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Shows how to create a Swup instance with the SwupHeadPlugin. The mount() method is invoked internally by swup.use().

```js
const swup = new Swup({ plugins: [new SwupHeadPlugin()] });
// mount() is invoked internally by swup.use()
```

--------------------------------

### Basic SwupHeadPlugin initialization

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Basic initialization of the SwupHeadPlugin in a swup application. Instantiates the plugin with default options and adds it to the plugins array.

```js
import Swup from 'swup';
import SwupHeadPlugin from '@swup/head-plugin';

const swup = new Swup({
  plugins: [
    new SwupHeadPlugin()
  ]
});
```

--------------------------------

### mount()

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Mounts the plugin by registering a hook before the `content:replace` event to update the head. This method is called automatically by swup when the plugin is used.

```APIDOC
## mount()

### Description
Mounts the plugin by registering a hook before the `content:replace` event to update the head. This method is called automatically by swup when the plugin is used.

### Method
`mount()`

### Parameters
None.

### Returns
Void.
```

--------------------------------

### Configure awaitAssets option

Source: https://github.com/swup/head-plugin/blob/main/README.md

Set awaitAssets to true to delay the transition until newly added assets have loaded. Currently only supports stylesheets. Defaults to false.

```javascript
new SwupHeadPlugin({
  awaitAssets: true
});
```

--------------------------------

### mount()

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

The mount() method is called by swup when the plugin is registered. It registers the updateHead handler for the content:replace hook.

```APIDOC
## `mount()`

### Description
An override of `Plugin.mount()`, invoked by swup when the plugin is registered via `swup.use(plugin)`. Registers `this.updateHead` as a **before** handler for the `'content:replace'` hook, so the head is updated before swup replaces the page content.

### Signature
`mount(): void` (inferred return)

### Parameters
None.

### Returns
`void`

### Example
```js
const swup = new Swup({ plugins: [new SwupHeadPlugin()] });
// mount() is invoked internally by swup.use()
```
```

--------------------------------

### SwupHeadPlugin constructor with persistAssets shortcut

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Constructor for the SwupHeadPlugin. Merges provided options over defaults and applies the persistAssets shortcut: if persistAssets is true and persistTags is falsy, persistTags is set to 'link[rel=stylesheet], script[src], style'. Note that an empty string for persistTags is treated as not set.

```ts
constructor(options: Partial<Options> = {}) {
	super();

	this.options = { ...this.defaults, ...options };

	// persistAssets is a shortcut for: persistTags with a default asset selector for scripts & styles
	if (this.options.persistAssets && !this.options.persistTags) {
		this.options.persistTags = 'link[rel=stylesheet], script[src], style';
	}
}
```

--------------------------------

### Options type for SwupHeadPlugin configuration

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/types.md

Defines the configuration options for the SwupHeadPlugin. All fields are required within the type, but the constructor accepts Partial<Options> and internal defaults supply the values. persistAssets defaults to false; persistTags accepts boolean, CSS selector string, or predicate function; awaitAssets delays transition until stylesheets load; attributes defaults to ['lang', 'dir']; timeout defaults to 3000 ms.

```typescript
type Options = {
	/** Whether to keep orphaned `link`, `style` and `script` tags from the old page. Default: `false` */
	persistAssets: boolean;
	/** Tags that will be persisted when a new page is loaded. Boolean, selector or predicate function. Default: `false` */
	persistTags: boolean | string | ((el: Element) => boolean);
	/** Delay the transition to the new page until all newly added assets have finished loading. Default: `false` */
	awaitAssets: boolean;
	/** Additional attributes of the head element to update. Default: ['lang', 'dir']. */
	attributes: (string | RegExp)[];
	/** How long to wait for assets before continuing anyway. Only applies if `awaitAssets` is enabled. Default: `3000` */
	timeout: number;
};
```

--------------------------------

### Basic usage of waitForStylesheet

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Creates a stylesheet link element, appends it to the document head, and waits for it to load with a 2-second timeout. After resolution, checks `loaded.sheet` to confirm the stylesheet was applied and logs the number of CSS rules.

```js
import { waitForStylesheet } from './waitForAssets.js'; // internal module

const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/app.css';
document.head.appendChild(link);

// Resolves when the stylesheet is applied (or after 2s, whichever is first)
const loaded = await waitForStylesheet(link, 2000);
if (loaded.sheet) {
  console.log('Stylesheet applied:', loaded.sheet.cssRules.length, 'rules');
}
```

--------------------------------

### SwupHeadPlugin constructor

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Constructor for the SwupHeadPlugin class, the default export of the package. It accepts an options object to configure persistence, asset handling, and attribute synchronization.

```APIDOC
## SwupHeadPlugin

### Description
Creates a new instance of the SwupHeadPlugin. The plugin synchronizes the contents of the `<head>` element of the current page with the head of the page being visited during a page transition. It also updates a configurable set of attributes (default `lang`, `dir`) on the `<html>` element, and can optionally defer the transition until newly added stylesheets have loaded.

### Constructor
`constructor(options: Partial<Options> = {})`

### Parameters
#### Options (Partial<Options>)
- **persistTags** (boolean) - Optional - Default: `false`. If `true`, tags matching the selector will be persisted across page loads.
- **persistAssets** (boolean) - Optional - Default: `false`. Shortcut for `persistTags` with a default asset selector for scripts & styles (`link[rel=stylesheet], script[src], style`).
- **awaitAssets** (boolean) - Optional - Default: `false`. If `true`, the transition will be deferred until newly added stylesheets have loaded.
- **attributes** (string[]) - Optional - Default: `['lang', 'dir']`. Attributes to update on the `<html>` element.
- **timeout** (number) - Optional - Default: `3000`. Timeout in milliseconds for awaiting assets.

### Example
```js
import SwupHeadPlugin from '@swup/head-plugin';

const headPlugin = new SwupHeadPlugin({
  persistAssets: true,
  awaitAssets: true,
  attributes: ['lang', 'dir', 'data-theme']
});
```
```

--------------------------------

### SwupHeadPlugin Class Properties

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Documentation for the class properties of the SwupHeadPlugin class, including name, requires, defaults, and options.

```APIDOC
## Class Property: `name`

### Description
A string identifier for the plugin, used by swup to recognize the plugin instance.

### Property
`name`

### Type
`string`

### Value
`'SwupHeadPlugin'`

### Source
`src/index.ts:22`
```

```APIDOC
## Class Property: `requires`

### Description
A semver range declaring the minimum swup version the plugin needs. swup uses this to validate compatibility (warnings are emitted if the host version is insufficient).

### Property
`requires`

### Type
`{ swup: string }`

### Value
`{ swup: '>=4.6' }`

### Source
`src/index.ts:24`
```

```APIDOC
## Class Property: `defaults`

### Description
The built-in default option values. Copied into `this.options` by the constructor and overridable per-instance.

### Property
`defaults`

### Type
`Options`

### Default Value
```ts
{
	persistTags: false,
	persistAssets: false,
	awaitAssets: false,
	attributes: ['lang', 'dir'],
	timeout: 3000
}
```

### Source
`src/index.ts:26-32`
```

```APIDOC
## Class Property: `options`

### Description
The effective merged options for this instance. The constructor computes it via shallow spread: `{ ...this.defaults, ...options }`, then applies the `persistAssets` shortcut. Note: because the spread is shallow, `attributes` arrays are shared by reference between `defaults` and instances unless overridden.

### Property
`options`

### Type
`Options`

### Default Value
`{ ...this.defaults, ...options }` from constructor

### Source
`src/index.ts:33`, assigned at `src/index.ts:38-43`
```

--------------------------------

### SwupHeadPlugin options property

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Effective merged options for this instance. The constructor computes it via shallow spread { ...this.defaults, ...options }.

```ts
options: Options;
```

--------------------------------

### Options type definition

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Type definition for the plugin's options object. Includes persistAssets, persistTags (boolean, string, or predicate), awaitAssets, attributes (array of strings or RegExp), and timeout.

```ts
type Options = {
	persistAssets: boolean;
	persistTags: boolean | string | ((el: Element) => boolean);
	awaitAssets: boolean;
	attributes: (string | RegExp)[];
	timeout: number;
};
```

--------------------------------

### mount() override for SwupHeadPlugin

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Override of Plugin.mount() invoked by swup when the plugin is registered via swup.use(plugin). Registers this.updateHead as a before handler for the 'content:replace' hook. Calling mount() again registers an additional handler because swup's registration is not deduplicated by this plugin.

```ts
mount() {
	this.before('content:replace', this.updateHead);
}
```

--------------------------------

### SwupHeadPlugin class definition

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

The default export of the package, extending the Plugin base class. It sets the plugin name, requires swup >=4.6, defines default options, and includes a constructor that merges options and handles persistAssets shortcut. The mount method registers a before hook for content:replace, and updateHead and isPersistentTag are defined.

```typescript
export default class SwupHeadPlugin extends Plugin {
	name = 'SwupHeadPlugin';

	requires = { swup: '>=4.6' };

	defaults: Options = {
		persistTags: false,
		persistAssets: false,
		awaitAssets: false,
		attributes: ['lang', 'dir'],
		timeout: 3000
	};
	options: Options;

	constructor(options: Partial<Options> = {}) {
		super();

		this.options = { ...this.defaults, ...options };

		// persistAssets is a shortcut for: persistTags with a default asset selector for scripts & styles
		if (this.options.persistAssets && !this.options.persistTags) {
			this.options.persistTags = 'link[rel=stylesheet], script[src], style';
		}
	}

	mount() {
		this.before('content:replace', this.updateHead);
	}

	updateHead: Handler<'content:replace'> = async (visit, { page: { html } }) => { ... };

	isPersistentTag(el: Element) { ... }
}
```

--------------------------------

### Configure persistAssets option

Source: https://github.com/swup/head-plugin/blob/main/README.md

Set persistAssets to true to keep orphaned link, style, and script tags from the old page. Defaults to false, meaning orphaned assets are removed.

```javascript
new SwupHeadPlugin({
  persistAssets: true
});
```

--------------------------------

### SwupHeadPlugin requires property

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Semver range declaring the minimum swup version needed. Used by swup to validate compatibility.

```ts
requires = { swup: '>=4.6' };
```

--------------------------------

### waitForAssets function definition

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Default export of the internal module. Filters candidate elements with the isStylesheet type guard (matching 'link[rel=stylesheet][href]') and maps each hit to waitForStylesheet. Returns one promise per matching element; empty or non-matching input yields an empty array. timeoutMs defaults to 0, which disables the timeout.

```ts
export default function waitForAssets(
	elements: Element[],
	timeoutMs: number = 0
): Promise<HTMLLinkElement>[] {
	return elements.filter(isStylesheet).map((el) => waitForStylesheet(el, timeoutMs));
}
```

--------------------------------

### waitForStylesheet

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Waits for a stylesheet link element to be loaded by polling its `sheet` property, with an optional timeout.

```APIDOC
## `waitForStylesheet`

### Description
Waits for a stylesheet link element to be loaded by polling its `sheet` property, with an optional timeout.

### Method
Function call

### Signature
```ts
export function waitForStylesheet(
	element: HTMLLinkElement,
	timeoutMs: number = 0
): Promise<HTMLLinkElement>
```

### Parameters
- **element** (`HTMLLinkElement`) - Required - A stylesheet link element whose `sheet` property will be polled.
- **timeoutMs** (`number`) - Optional, default `0` - Max wait in ms. `0` disables the timeout, so the promise only resolves once `element.sheet` is truthy; any positive number schedules a forced `resolve(element)` after that delay, clearing the pending poll.

### Return Type
`Promise<HTMLLinkElement>` — resolves with the same `element` that was passed in, whether it loaded or the timeout fired. The promise **never rejects** (no error path exists in the implementation).

### Behavior
- Polls `element.sheet` every **10 ms** (`setTimeout(..., 10)` re-scheduling) until it is truthy, then resolves with the element. The polling relies on the element being connected to the document — a detached stylesheet whose `sheet` never becomes populated will only resolve via a positive `timeoutMs`.
- If `timeoutMs > 0`, a parallel timer fires after `timeoutMs`: it clears the pending poll (`clearTimeout(timeoutId)`) and resolves with the element.
- If `timeoutMs <= 0`, no timeout timer is set and resolution happens only when `sheet` is observed.

### Examples
```js
import { waitForStylesheet } from './waitForAssets.js'; // internal module

const link = document.createElement('link');
link.rel = 'stylesheet';
link.href = '/app.css';
document.head.appendChild(link);

// Resolves when the stylesheet is applied (or after 2s, whichever is first)
const loaded = await waitForStylesheet(link, 2000);
if (loaded.sheet) {
  console.log('Stylesheet applied:', loaded.sheet.cssRules.length, 'rules');
}
```

Timeout variant — never blocks forever:

```js
const result = await waitForStylesheet(link, 1000);
// result is always the element; check element.sheet to see whether it actually loaded
```
```

--------------------------------

### SwupHeadPlugin name property

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Class property that defines the plugin identifier string used by swup.

```ts
name = 'SwupHeadPlugin';
```

--------------------------------

### Configure persistTags option

Source: https://github.com/swup/head-plugin/blob/main/README.md

Define which tags will be persisted when a new page is loaded. Defaults to false, removing all orphaned tags. Accepts a boolean, a CSS selector string, or a function.

```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 attributes option

Source: https://github.com/swup/head-plugin/blob/main/README.md

Update additional attributes of the html element. Accepts an array of strings or regular expression instances. By default, lang and dir are updated.

```javascript
{
  attributes: ['lang', 'dir', 'style', /^data-/]
}
```

--------------------------------

### Default options object for SwupHeadPlugin

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/configuration.md

The built-in defaults object defined in src/index.ts:26-32. These values are merged with user options via a shallow spread, so only keys passed by the user are overridden.

```ts
defaults: Options = {
	persistTags: false,
	persistAssets: false,
	awaitAssets: false,
	attributes: ['lang', 'dir'],
	timeout: 3000
};
```

--------------------------------

### shouldManageTag function

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Gate applied to both removal and addition. Returns false for title elements and elements matching [data-swup-theme]; otherwise true. Title elements are never added or removed by this module, and swup theme styles are left untouched.

```ts
function shouldManageTag(el: Element) {
	// Let swup manage the title tag
	if (el.localName === 'title') {
		return false;
	}
	// Leave swup theme styles untouched
	if (el.matches('[data-swup-theme]')) {
		return false;
	}
	return true;
}
```

--------------------------------

### Direct invocation of updateHead handler

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Direct invocation of the updateHead handler, as done in tests. It simulates the before-hook payload by creating a visit and setting visit.to.document, then calls plugin.updateHead with the payload. After the call, document.head reflects the next page's head.

```js
const plugin = new SwupHeadPlugin();
swup.use(plugin);

// Simulate the before-hook payload
const visit = swup.createVisit({ url: '/next' });
visit.to.document = new DOMParser().parseFromString(
  '<html><head><title>Next</title></head><body></body></html>',
  'text/html'
);

await plugin.updateHead(visit, { page: { html: '<html><head></head><body></body></html>', url: '/next' } });
// document.head now reflects the next page's <head>
```

--------------------------------

### updateHead

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Handler for the `content:replace` hook that updates the `<head>` element and `<html>` attributes based on the new page's HTML. It is called automatically by swup during page transitions.

```APIDOC
## updateHead

### Description
Handler for the `content:replace` hook that updates the `<head>` element and `<html>` attributes based on the new page's HTML. It is called automatically by swup during page transitions.

### Method
`updateHead: Handler<'content:replace'>`

### Parameters
- **visit** (Visit) - Required - The visit object provided by swup.
- **page** (object) - Required - The page object containing the new page's HTML.
  - **html** (string) - Required - The HTML string of the new page.

### Returns
Promise<void>.
```

--------------------------------

### updateHead handler for content:replace hook

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

The updateHead handler for the 'content:replace' hook. It merges head contents, updates attributes if configured, and optionally waits for assets to load. The handler is async and rejects only if Promise.all rejects; waitForStylesheet never rejects, so it resolves successfully in practice. No try/catch exists, so unexpected exceptions propagate to swup's hook machinery.

```ts
updateHead: Handler<'content:replace'> = async (visit, { page: { html } }) => {
	const { awaitAssets, attributes, timeout } = this.options;

	const newDocument = visit.to.document!;

	const { removed, added } = mergeHeadContents(document.head, newDocument.head, {
		shouldPersist: (el) => this.isPersistentTag(el)
	});

	this.swup.log(`Removed ${removed.length} / added ${added.length} tags in head`);

	if (attributes?.length) {
		updateAttributes(document.documentElement, newDocument.documentElement, attributes);
	}

	if (awaitAssets) {
		const assetLoadPromises = waitForAssets(added, timeout);
		if (assetLoadPromises.length) {
			this.swup.log(`Waiting for ${assetLoadPromises.length} assets to load`);
			await Promise.all(assetLoadPromises);
		}
	}
};
```

--------------------------------

### waitForStylesheet implementation

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Polls the `sheet` property of a stylesheet link element every 10 ms until it becomes truthy, then resolves with the element. If `timeoutMs` is positive, a parallel timer forces resolution after that delay and clears the pending poll. The promise never rejects; a detached element will only resolve via a positive timeout.

```ts
export function waitForStylesheet(
	element: HTMLLinkElement,
	timeoutMs: number = 0
): Promise<HTMLLinkElement> {
	let timeoutId: ReturnType<typeof setTimeout>;

	const whenLoaded = (cb: () => void) => {
		if (element.sheet) {
			cb();
		} else {
			timeoutId = setTimeout(() => whenLoaded(cb), 10);
		}
	};

	return new Promise((resolve) => {
		whenLoaded(() => resolve(element));
		if (timeoutMs > 0) {
			setTimeout(() => {
				if (timeoutId) clearTimeout(timeoutId);
				resolve(element);
			}, timeoutMs);
		}
	});
}
```

--------------------------------

### updateHead

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

The updateHead handler is the core method that updates the document head during a swup visit. It merges head contents, optionally syncs attributes, and can wait for assets to load.

```APIDOC
## `updateHead`

### Description
An async handler for the `'content:replace'` hook that updates the document head with the new page's head contents, optionally syncing attributes and waiting for assets to load.

### Signature
`updateHead: Handler<'content:replace'> = async (visit, { page: { html } }) => { ... }`

### Parameters
- **visit** (swup `Visit`) - The active visit object. `visit.to.document` is the parsed document of the target page (non-null assertion).
- **`{ page: { html } }`** (`{ page: { html: string } }`) - The hook payload; the plugin uses only `page.html` (the incoming page's raw HTML string).

### Behavior
1. Resolves `awaitAssets`, `attributes`, `timeout` from `this.options`.
2. Reads the target page document from `visit.to.document` (non-null assertion).
3. Calls `mergeHeadContents` with the current `document.head` and the new document's head, passing `shouldPersist: (el) => this.isPersistentTag(el)`. This adds and removes `<head>` children on the live document and returns `{ removed, added }`.
4. Logs `Removed ${removed.length} / added ${added.length} tags in head` through `this.swup.log`.
5. If `attributes` has any entries, calls `updateAttributes` on `document.documentElement` (current `<html>`) with the new document's `<html>` element, syncing only the filtered attributes.
6. If `awaitAssets` is enabled, calls `waitForAssets` with the added elements and the configured `timeout`; if any promises are returned (i.e., added stylesheets with `href`), logs `Waiting for N assets to load` and awaits `Promise.all(...)` — delaying the `content:replace` before-hook, which defers the transition until the stylesheets are loaded (up to `timeout` ms each).
7. The function is `async`; it **rejects only if `Promise.all` rejects**. `waitForStylesheet` never rejects, so in practice this handler resolves successfully. No try/catch exists in the handler; any unexpected exception in the merge/attribute logic propagates to swup's hook machinery.

### Returns
`Promise<void>` (async handler; swup awaits before-hook handlers).

### Example (direct invocation)
```js
const plugin = new SwupHeadPlugin();
swup.use(plugin);

// Simulate the before-hook payload
const visit = swup.createVisit({ url: '/next' });
visit.to.document = new DOMParser().parseFromString(
  '<html><head><title>Next</title></head><body></body></html>',
  'text/html'
);

await plugin.updateHead(visit, { page: { html: '<html><head></head><body></body></html>', url: '/next' } });
// document.head now reflects the next page's <head>
```
```

--------------------------------

### Timeout variant of waitForStylesheet

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Shows the timeout variant that never blocks forever: after 1 second, `result` is always the element, so you must check `element.sheet` to determine whether the stylesheet actually loaded.

```js
const result = await waitForStylesheet(link, 1000);
// result is always the element; check element.sheet to see whether it actually loaded
```

--------------------------------

### compareTags function

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Determines tag equality by exact serialized HTML equality (outerHTML string comparison). Any difference in attribute order, attribute values, or inner content makes tags unequal, causing the new tag to be added and the old one removed.

```ts
function compareTags(oldTag: Element, newTag: Element) {
	return oldTag.outerHTML === newTag.outerHTML;
}
```

--------------------------------

### getTagsToAdd function signature

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Returns entries for every element of newEls that has no equal counterpart in currentEls, with index set to the element's index within newEls.

```ts
function getTagsToAdd(currentEls: Element[], newEls: Element[]): ElementCollection
```

--------------------------------

### getTagsToRemove function signature

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Returns entries for every element of currentEls that has no equal counterpart in newEls, using compareTags for equality. Index is not set on remove entries.

```ts
function getTagsToRemove(currentEls: Element[], newEls: Element[]): ElementCollection
```

--------------------------------

### isStylesheet type guard

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/waitForAssets.md

Type-guard predicate matching `<link>` elements with `rel="stylesheet"` and an `href` attribute. Requires `href` to be present and matches the `rel` attribute exactly; `<link>` elements loaded dynamically without `href`, or with other `rel` values, are ignored by `waitForAssets`.

```ts
function isStylesheet(el: Element): el is HTMLLinkElement {
	return el.matches('link[rel=stylesheet][href]');
}
```

--------------------------------

### getAttributes helper function implementation

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/updateAttributes.md

Internal helper that returns the list of attributes on an element that match the given filters. With an empty filters array, all attributes are returned. Otherwise, an attribute is included if any filter matches its name, either by exact string equality or by RegExp test.

```TypeScript
function getAttributes(el: Element, filters: (string | RegExp)[] = []): Attr[] {
	const all = Array.from(el.attributes);
	if (!filters.length) return all;

	return all.filter(({ name }) =>
		filters.some((pattern) =>
			pattern instanceof RegExp ? pattern.test(name) : name === pattern
		)
	);
}
```

--------------------------------

### ElementCollection type

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/types.md

Internal-only accumulator type used by getTagsToRemove and getTagsToAdd. The index property is set only for add candidates so the element can be inserted after its successor.

```ts
type ElementCollection = { el: Element; index?: number }[];
```

--------------------------------

### isPersistentTag

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Method to determine if a tag should be persisted when orphaned, based on the persistTags option.

```APIDOC
## `isPersistentTag`

### Description
Determines whether a tag should be kept when it is orphaned (present in the old head but absent from the new head). Dispatches on the `persistTags` option value.

### Signature
`isPersistentTag(el: Element): boolean`

### Parameters
- **el** (Element) - Required - The element to test.

### Behavior
| `persistTags` value | Behavior |
|---------------------|----------|
| `(el: Element) => boolean` | The predicate is called with the element and its return value is returned directly. |
| non-empty `string` | `el.matches(selector)` — the element must match the CSS selector. |
| `''` (empty string) | Falls through to `Boolean(persistTags)` → `false` (treated as "don't persist"). |
| `true` | `Boolean(true)` → every orphaned tag is persisted. |
| `false` | `Boolean(false)` → no orphaned tag is persisted. |

### Example
```js
const plugin = new SwupHeadPlugin({ persistTags: 'style[data-keep]' });

document.querySelectorAll('style').forEach((style) => {
  if (plugin.isPersistentTag(style)) {
    console.log('This style tag will survive transitions');
  }
});
```
```

--------------------------------

### updateAttributes function implementation

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/updateAttributes.md

The default export function that synchronizes attributes from a source element to a target element. It sets attributes from the source on the target and removes attributes from the target that are not present on the source, based on the provided filters.

```TypeScript
export default function updateAttributes(
	target: Element,
	source: Element,
	filters: (string | RegExp)[] = []
): void {
	const keep = new Set<string>();

	for (const { name, value } of getAttributes(source, filters)) {
		target.setAttribute(name, value);
		keep.add(name);
	}

	for (const { name } of getAttributes(target, filters)) {
		if (!keep.has(name)) {
			target.removeAttribute(name);
		}
	}
}
```

--------------------------------

### mergeHeadContents function

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

Core function that merges the current document head with a new head. Mutates currentHead in place, removes tags not present in newHead (unless shouldPersist returns true), and inserts cloned tags from newHead. Returns { removed, added } arrays.

```ts
export default function mergeHeadContents(
	currentHead: HTMLHeadElement,
	newHead: HTMLHeadElement,
	{ shouldPersist = () => false }: { shouldPersist?: (el: Element) => boolean } = {}
) {
	const currentTags = Array.from(currentHead.children);
	const newChildren = Array.from(newHead.children);

	const addTags = getTagsToAdd(currentTags, newChildren);
	const removeTags = getTagsToRemove(currentTags, newChildren);

	// Remove tags in reverse to keep indexes, keep persistant elements
	removeTags
		.reverse()
		.filter(({ el }) => shouldManageTag(el))
		.filter(({ el }) => !shouldPersist(el))
		.forEach(({ el }) => currentHead.removeChild(el));

	// Insert tag *after* previous version of itself to preserve JS variable scope and CSS cascade
	const newAddTags = addTags
		.filter(({ el }) => shouldManageTag(el))
		.map((tag) => {
			let newEl = tag.el.cloneNode(true) as Element;
			currentHead.insertBefore(newEl, currentHead.children[(tag.index || 0) + 1] || null);

			return { ...tag, el: newEl };
		});

	return {
		removed: removeTags.map(({ el }) => el),
		added: newAddTags.map(({ el }) => el)
	};
}
```

--------------------------------

### Return type of mergeHeadContents

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/mergeHeadContents.md

TypeScript type annotation for the return value of mergeHeadContents. Shows the shape of the returned object with removed and added arrays of Element.

```ts
{
	removed: Element[];   // tags removed from currentHead (only those filtered by shouldManageTag)
	added: Element[];     // new, cloned tags inserted into currentHead (only those filtered by shouldManageTag)
}
```

--------------------------------

### mergeHeadContents options object type

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/types.md

Inline object type for the third parameter of mergeHeadContents. The optional shouldPersist property defaults to a function returning false, which determines whether an orphaned element is kept instead of removed from the current head.

```ts
{
	shouldPersist = () => false
}: { shouldPersist?: (el: Element) => boolean }
```

--------------------------------

### isPersistentTag(el: Element)

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Determines whether a given element should be persisted across page loads based on the configured `persistTags` selector. This method is used internally by the plugin.

```APIDOC
## isPersistentTag(el: Element)

### Description
Determines whether a given element should be persisted across page loads based on the configured `persistTags` selector. This method is used internally by the plugin.

### Method
`isPersistentTag(el: Element)`

### Parameters
- **el** (Element) - Required - The element to check.

### Returns
boolean - `true` if the element matches the persist selector, otherwise `false`.
```

--------------------------------

### isPersistentTag method

Source: https://github.com/swup/head-plugin/blob/main/_autodocs/api-reference/SwupHeadPlugin.md

Determines whether a tag should be kept when orphaned. Dispatches on the `persistTags` option: if it's a function, calls it with the element; if a non-empty string, uses `el.matches(selector)`; otherwise falls back to `Boolean(persistTags)`. Used internally by `updateHead` as the `shouldPersist` callback.

```ts
isPersistentTag(el: Element) {
	const { persistTags } = this.options;
	if (typeof persistTags === 'function') {
		return persistTags(el);
	}
	if (typeof persistTags === 'string' && persistTags.length > 0) {
		return el.matches(persistTags);
	}
	return Boolean(persistTags);
}
```
Tokens:
Raw