@popeindustries/lit-html

Seamlessly and efficiently use @popeindustries/lit-html-server rendered HTML to hydrate lit-html templates in the browser.

Features

- seamless hydration: first call to render() will hydrate if possible, with subsequent calls updating the existing DOM by forwarding to lit-html.render().
- hydration errors will cause the server rendered markup to be cleared and replaced with the result of lit-html.render().
- render multiple sub-trees in the same container.
- easily enable lazy (partial/deferred) web component hydration with lazy-hydration-mixin and hydrate:idle or hydrate:visible attributes.

Usage

Install with npm/yarn/pnpm:

``bash
$ npm install --save @popeindustries/lit-html
`

Given the following server rendered HTML:

`html



Some Title

Some paragraph of text to show that multiple

hydration sub-trees can exist in the same container.

This is the main page content.

`

...import your lit-html templates used on the server:

`js
import { html } from '@popeindustries/lit-html';

function renderMenu(data) {
const { negative, sections } = data;
return html

;
}
function renderPage(data) {
return html

This is the main page content.

;
}
`

...and render:

`js
import { render } from '@popeindustries/lit-html';

render(renderMenu(data), document.body, { renderBefore: document.querySelector('body > p') });
render(renderPage(data), document.body, { renderBefore: document.querySelector('body > footer') });
`

> Note
> Due to how the lit* family of packages are minified and mangled for production, the @popeindustries/lit-html package is forced to _vendor_ the lit-html package. This shouldn't affect normal use as long as application code does not mix imports from @popeindustries/lit-html and lit-html.

lazy-hydration-mixin

When hydrating sub-trees containing nested web components, it is often necessary to control the hydration order to allow parent elements to pass data down to their children. When rendering web components on the server, lit-html-server adds a hydrate:defer attribute that may be used to determine when hydration should take place.

The lazy-hydration-mixin is an easy way to add support for basic hydration deferral by delaying the call to the base class's connectedCallback() method:

`js
import { html, render } from '@popeindustries/lit-html';
import { lazyHydrationMixin } from '@popeindustries/lit-html/lazy-hydration-mixin.js';

class MyBaseClass extends HTMLElement {
// Called when hydrate:defer attribute is removed
connectedCallback() {
render(this.render(), this, { host: this });
}
}

class MyEl extends lazyHydrationMixin(MyBaseClass) {
// Called by browser when instance connected
connectedCallback() {
super.connectedCallback(); // super here is the mixin class
}
render() {
return htmlsome content;
}
}
`

This simple mechanism also enables additional forms of deferral, and the lazy-hydration-mixin includes two additional strategies:

#### hydrate:idle

Adding the hydrate:idle attribute to the element waits until the browser has performed any pending high priority work before hydrating the element (requires the requestIdleCallback API, otherwise it falls back to default behaviour):

`html

`

#### hydrate:visible

Adding the hydrate:visible attribute to the element waits until the element is visible in the viewport before hydrating the element (requires the IntersectionObserver API, otherwise it falls back to default behaviour).

`html

``