@lit-labs/observers

Reactive controllers that make it easy to use the web platform observer classes with Lit.

@lit-labs/observers includes reactive controllers for:

• MutationObserver
• ResizeObserver
• IntersectionObserver
• PerformanceObserver

[!WARNING]

This package is part of Lit Labs. It is published in order to get feedback on the design and may receive breaking changes or stop being supported.

Please read our Lit Labs documentation before using this library in production.

Give feedback: https://github.com/lit/lit/discussions/3355

Overview

The modern web platform provides a number of observer helpers that can be used to detect changes to which web applications may want to react. By managing one of these observers with a reactive controller, changes can be easily integrated into the Lit reactive update lifecycle. The controller can also help manage observer cleanup and rendering in response to changes.

Installation

From inside your project folder, run:

$ npm install @lit-labs/observers

Usage

IntersectionController

IntersectionController attaches a IntersectionObserver to the host and requests updates whenever the IntersectionObserver observes changes to the intersection state of the targets.

The controller can also compute and store an arbitrary value each time changes occur.

Import

import {IntersectionController} from '@lit-labs/observers/intersection-controller.js';

Constructor

constructor(
  host: ReactiveControllerHost & Element,
  {target, config, callback, skipInitial}: IntersectionControllerConfig<T>
)

Config

• config: IntersectionObserverInit: Configuration object for the IntersectionObserver.
• target?: Element | null: The element to observe. In addition to configuring the target here, the observe method can be called to observe additional targets. When not specified, the target defaults to the host. If set to null, no target is automatically observed. Only the configured target will be re-observed if the host connects again after unobserving via disconnection.
• callback?: IntersectionValueCallback<T>: The callback used to process detected changes into a value stored in the controller's value property.
• skipInitial?: boolean: By default the callback is called without changes when a target is observed. This is done to help manage initial state, but this setup step can be skipped by setting this to true.

Properties and Methods

• value?: T: The result of processing the observer's changes via the callback function passed to the config.
• observe(target: Element): Observe the target element. The controller's target is automatically observed when the host connects.
• unobserve(target: Element): Unobserve the target element.
• disconnect(): Disconnects the observer. This is done automatically when the host disconnects.

MutationController

MutationController attaches a MutationObserver to the host and requests updates whenever the MutationObserver observes changes to the DOM.

The controller can also compute and store an arbitrary value each time changes occur.

Example

import {MutationController} from '@lit-labs/observers/mutation-controller.js';
// ...

class MyElement extends LitElement {
  private _observer = new MutationController(this, {
    config: {attributes: true},
  });

  render() {
    return html` ${this._observer.value ? `Attributes set!` : ``} `;
  }
}

Import

import {MutationController} from '@lit-labs/observers/mutation-controller.js';

Constructor

new MutationController<T = unknown>(
  host: ReactiveControllerHost & Element,
  {target, config, callback, skipInitial}: MutationControllerConfig<T>
)

The type parameter <T> is the type of the value property and the return type of the callback option.

MutationControllerConfig

• config: MutationObserverInit: Configuration object for the MutationObserver.
• target?: Element | null: The element to observe. In addition to configuring the target here, the observe method can be called to observe additional targets. When not specified, the target defaults to the host. If set to null, no target is automatically observed. Only the configured target will be re-observed if the host connects again after unobserving via disconnection.
• callback?: MutationValueCallback<T>: The callback used to process detected changes into a value stored in the controller's value property.
• skipInitial?: boolean: By default the callback is called without changes when a target is observed. This is done to help manage initial state, but this setup step can be skipped by setting this to true.

Properties and Methods

• value: The result of processing the observer's changes via the callback function passed to the config.
• observe(target: Element): Observe the target element. The controller's target is automatically observed when the host connects.
• disconnect(): Disconnects the observer. This is done automatically when the host disconnects.

PerformanceController

PerformanceController attaches a PerformanceObserver to the host and requests updates whenever the PerformanceObserver observes receives new performance metrics.

Import

import {PerformanceController} from '@lit-labs/observers/performance-controller.js';

Constructor

constructor(
  host: ReactiveControllerHost,
  {config, callback, skipInitial}: PerformanceControllerConfig<T>
)

PerformanceControllerConfig

• config: PerformanceObserverInit: Configuration object for the MutationObserver.
• callback?: PerformanceValueCallback<T>: The callback used to process detected changes into a value stored in the controller's value property.
• skipInitial?: boolean: By default the callback is called without changes when a target is observed. This is done to help manage initial state, but this setup step can be skipped by setting this to true.

Properties and Methods

• value: The result of processing the observer's changes via the callback function passed to the config.
• observe(target: Element): Observe the target element. The controller's target is automatically observed when the host connects.
• disconnect(): Disconnects the observer. This is done automatically when the host disconnects.

ResizeController

ResizeController attaches a ResizeObserver to the host and requests updates whenever the ResizeObserver detects size changes to its targets. The controller can also compute and store an arbitrary value each time changes occur.

Import

import {ResizeController} from '@lit-labs/observers/resize-controller.js';

Constructor

constructor(
  host: ReactiveControllerHost & Element,
  {target, config, callback, skipInitial}: ResizeControllerConfig<T>
)

ResizeControllerConfig

• config?: ResizeObserverOptions: Configuration object for the ResizeController.
• target?: Element | null: The element to observe. In addition to configuring the target here, the observe method can be called to observe additional targets. When not specified, the target defaults to the host. If set to null, no target is automatically observed. Only the configured target will be re-observed if the host connects again after unobserving via disconnection.
• callback?: ResizeValueCallback<T>: The callback used to process detected changes into a value stored in the controller's value property.
• skipInitial?: boolean: By default the callback is called without changes when a target is observed. This is done to help manage initial state, but this setup step can be skipped by setting this to true. }

Properties and Methods

• value?: T: The result of processing the observer's changes via the callback function passed to the config.
• observe(target: Element): Observe the target element. The controller's target is automatically observed when the host connects.
• unobserve(target: Element): Unobserve the target element.
• disconnect(): Disconnects the observer. This is done automatically when the host disconnects.

Contributing

Please see CONTRIBUTING.md.