Custom Morphers#

The morpher is a library used to update specific parts of the DOM element instead of replacing the entire element. This improves performance and maintains the state of unchanged DOM elements, such as the cursor position in an input.

The default morpher used in Unicorn is morphdom. The only alternative morpher available is the Alpine.js morph plugin.

Morphdom#

morphdom is the default morpher so no extra settings or installation is required to use it.

Alpine#

Components which use both Unicorn and Alpine.js should use the Alpine.js morpher to prevent losing state when it gets re-rendered.

Django Settings#

# settings.py

UNICORN = {
    ...
    "MORPHER": {
        "NAME": "alpine",
    }
    ...
}

Note

MORPHER.RELOAD_SCRIPT_ELEMENTS is not currently supported for the Alpine.js morpher.

JavaScript Installation#

Alpine.js is not included in Unicorn so you will need to manually include it. Make sure to include Alpine.js and the morpher plugin by adding the following line to your template before {% unicorn_scripts %}.

...
<head>
  <script defer src="https://unpkg.com/@alpinejs/[email protected]/dist/cdn.min.js"></script>
  <script defer src="https://unpkg.com/[email protected]/dist/cdn.min.js"></script>
  {% unicorn_scripts %}
</head>
...