6.3 KiB
Lit Helpers
A library with helpers functions for working with lit-html and lit-element
Installation
npm i --save @open-wc/lit-helpers
Spread directives
Spread directives can be used to set an arbitrary collection of properties, attributes or event listeners on an element without knowing all the keys in advance.
The spread directives work by taking in an object of data to spread. Because of lit-html syntax, we need one attribute to apply the directive to. It doesn't actually matter what the name of this attribute is, we recommend sticking to the convention of using ... as the attribute name.
Regular spread
The regular spread directive can be used to set properties, attribute or event listeners. It uses the same syntax as lit-html for distinguishing different types of bindings:
import { html, render } from 'lit-html';
import { spread } from '@open-wc/lit-helpers';
render(
html`
<div
...=${spread({
'my-attribute': 'foo',
'?my-boolean-attribute': true
'.myProperty': { foo: 'bar' },
'@my-event': () => console.log('my-event fired'),
})}
></div>
`,
document.body,
);
Property spread
Because spreading properties is a common use case, you can use the spreadProps directive so that you don't need prefix each property with a .. This is especially useful when the data comes from external sources.
import { html, render } from 'lit-html';
import { spreadProps } from '@open-wc/lit-helpers';
render(html` <div ...="${spreadProps({ propertyA: 'a', propertyB: 'b' })}"></div> `, document.body);
Attribute spread
Since spread already spreads attribute as the default case, we do not need a separate spreadAttributes directive.
Re-rendering
When re-rendering, values are updated if they changed from the previous value. We use the same strict equality check (!==) as lit-html for this.
Unlike lit-html, when spreading attributes we remove the attribute if it is set to null or undefined.
If an entry in the spread data is removed, the property is set to undefined, the attribute is removed or the event listener is deregistered.
Example:
function renderSpread(data) {
render(html` <div ...="${spread(data)}"></div> `, document.body);
}
// result: <div foo="bar">
renderSpread({ foo: 'bar' });
// result: <div foo="buz">
renderSpread({ foo: 'buz' });
// result: <div foo="buz" lorem="ipsum">
renderSpread({ foo: 'buz', lorem: 'ipsum' });
// result: <div foo="buz">
renderSpread({ foo: 'buz' });
// result: <div>
renderSpread({ foo: 'undefined' });
Live binding
For efficiency, lit-html does not set properties or attributes if they did not change since the previous render. This can cause problems when the properties are changed outside of lit-html's control. The live directive can be used to dirty check the element's live value, and set the property or attribute if it changed.
A great example for this, is the DOM element's scrollTop property which changes without lit-html knowing about it when the user scrolls.
By using the live directive, you can make sure it is always in sync with the value rendered by lit-html:
html` <my-element .scrollTop=${live(scrollTop)}></my-element> `;
Privately Settable Read-Only Properties
ReadOnlyPropertiesMixin provides a way for based on LitElement (or it's parent class UpdatingElement) to define properties by adding readOnly: true to their property declaration. Those properties are read-only from the outside, but can be updated internally with the setReadOnlyProperties method.
import { ReadOnlyPropertiesMixin } from '@open-wc/lit-helpers';
import { LitElement } from 'lit-element';
class SettableElement extends ReadOnlyPropertiesMixin(LitElement) {
static get properties() {
return {
timestamp: { type: Number, readOnly: true },
};
}
constructor() {
super();
this.timestamp = Date.now();
}
updateTime() {
this.setReadOnlyProperties({ timestamp: Date.now() });
}
render() {
return html`
<button @click="${this.updateTime}">Update Time</button>
<time>${this.timestamp}</time>
`;
}
}
The mixin also supports the @property decorator.
import { ReadOnlyPropertiesMixin } from '@open-wc/lit-helpers';
import { LitElement, property } from 'lit-element';
class SettableElement extends ReadOnlyPropertiesMixin(LitElement) {
@property({ type: Number, readOnly: true }) timestamp = Date.now();
updateTime() {
this.setReadOnlyProperties({ timestamp: Date.now() });
}
render() {
return html`
<button @click="${this.updateTime}">Update Time</button>
<time>${this.timestamp}</time>
`;
}
}
Known Limitations
Order of Application Matters
Currently, this mixin only works properly when applied to LitElement (or UpdatingElement) directly. In other words, if you have a component which inherits like the example below, then ReadOnlyPropertiesMixin must be applied to LitElement only.
// Bad
class Lowest extends LitElement {
@property({ readOnly: true }) lowestProperty = undefined;
}
class Highest extends ReadOnlyPropertiesMixin(Lowest) {
// will not work as expected
@property({ readOnly: true }) highestProperty = undefined;
}
// Good
class Lowest extends ReadOnlyPropertiesMixin(LitElement) {
@property({ readOnly: true }) lowestProperty = undefined;
}
class Highest extends Lowest {
@property({ readOnly: true }) highestProperty = undefined;
}
Properties Must be Initialized
Read only properties must be initialized with some value, even if the value is undefined. This is because the mixin allows one free setting, to support class field initialization.
// Bad
class Uninitialized extends ReadOnlyPropertiesMixin(LitElement) {
@property({ readOnly: true }) uninitialized;
}
// Good
class Initialized extends ReadOnlyPropertiesMixin(LitElement) {
@property({ readOnly: true }) initialized = undefined;
}