https://github.com/daun/swup-morph-plugin

A swup plugin for morphing DOM nodes in place
https://github.com/daun/swup-morph-plugin

dom morph plugin swup

Last synced: about 2 months ago
JSON representation

A swup plugin for morphing DOM nodes in place

• Host: GitHub
• URL: https://github.com/daun/swup-morph-plugin
• Owner: daun
• License: mit
• Created: 2020-05-26T17:49:32.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2024-11-27T09:35:31.000Z (2 months ago)
• Last Synced: 2024-12-10T12:37:41.611Z (2 months ago)
• Topics: dom, morph, plugin, swup
• Language: TypeScript
• Homepage:
• Size: 1.24 MB
• Stars: 19
• Watchers: 1
• Forks: 2
• Open Issues: 4
• Metadata Files:
  • Readme: README.md
  • Changelog: CHANGELOG.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Swup Morph Plugin

A [swup](https://swup.js.org) plugin for morphing dom nodes into the new page.

Allows morphing containers into the new page without replacing or animating them. The prime use

cases are headers and menus on multi-language sites: you might not want to swap these elements out

with a transition on each page visit, however you'd still want to update any URLs, labels or

classnames when the user switches between languages.

Behind the scenes, it uses

[morphdom](https://github.com/patrick-steele-idem/morphdom) to update the

existing DOM nodes to match the same DOM nodes on the new page being loaded.

This will leave any event handlers in place, as opposed to setting `innerHTML`

on the target.

## Installation

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

```bash

npm install swup-morph-plugin

```

```js

import SwupMorphPlugin from 'swup-morph-plugin';

```

Or include the minified production file from a CDN:

```html

```

## Usage

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

```javascript

const swup = new Swup({

  plugins: [new SwupMorphPlugin()]

});

```

## Morphed containers

The plugin provides two ways of choosing the containers to be morphed:

### Container option

Pass in a list of selectors into the plugin options to let it know about morphable containers. Use

this method if you have a limited and predictable number of containers to morph.

```javascript

new SwupMorphPlugin({

  containers: ['#nav']

})

```

```html

  

  

```

### Data attribute

Add a `data-swup-morph` attribute with a **unique** identifier on containers to be morphed. The

plugin will find all containers with this attribute and match the outgoing and incoming versions

of each container by the value of the attribute. Use this method if you have lots of dynamically

created morphable containers.

```html

  

  

```

## Options

### containers

Array of specific DOM selectors that will be morphed into the new page.

```javascript

{

  containers: ['#nav']

}

```

### updateCallbacks

Callbacks to run before elements are updated. This can be used to persist or

discard certain attributes. If the callback returns `false`, the element will

not be updated.

See the [morphdom docs](https://github.com/patrick-steele-idem/morphdom#api) on

the `onBeforeElUpdated` option for details.

```javascript

{

  containers: ['#widget'],

  updateCallbacks: [

    (fromEl, toEl) => {

      // Persist ARIA attributes on buttons and inputs

      if (fromEl.hasAttribute('aria-pressed')) {

        toEl.setAttribute('aria-pressed', fromEl.getAttribute('aria-pressed'))

      }

    }

  ]

}

```