@popeindustries/lit-html
v5.2.4
Published
Seamlessly and efficiently use @popeindustries/lit-html-server rendered HTML to hydrate lit-html templates in the browser
Downloads
6,964
Readme
@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 tolit-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-mixinandhydrate:idleorhydrate:visibleattributes.
Usage
Install with npm/yarn/pnpm:
$ npm install --save @popeindustries/lit-htmlGiven the following server rendered HTML:
<body>
<h1>Some Title</h1>
<!--lit qKZ2lAadfCg=-->
<nav negative>
<!--lit-attr 1--><!--lit-child--><!--lit-child zRvOSEJDeXc=--><button><!--lit-child-->one<!--/lit-child--></button
><!--/lit-child--><!--lit-child zRvOSEJDeXc=--><button><!--lit-child-->two<!--/lit-child--></button
><!--/lit-child--><!--lit-child zRvOSEJDeXc=--><button><!--lit-child-->three<!--/lit-child--></button
><!--/lit-child--><!--/lit-child-->
</nav>
<!--/lit-->
<p>
Some paragraph of text to show that multiple<br />
hydration sub-trees can exist in the same container.
</p>
<!--lit 83OJYYYBUzs=-->
<main>This is the main page content.</main>
<!--/lit-->
<footer>Some footer</footer>
</body>...import your lit-html templates used on the server:
import { html } from '@popeindustries/lit-html';
function renderMenu(data) {
const { negative, sections } = data;
return html`<nav ?negative="${negative}">${sections.map((section) => html`<button>${section}</button>`)}</nav>`;
}
function renderPage(data) {
return html`<main>This is the main page content.</main>`;
}...and render:
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-htmlpackage is forced to vendor thelit-htmlpackage. This shouldn't affect normal use as long as application code does not mix imports from@popeindustries/lit-htmlandlit-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:
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 html`<span>some content</span>`;
}
}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):
<my-el hydrate:idle></my-el>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).
<my-el hydrate:visible></my-el>