Lit Modal Portal

I don't use it much, but I do like the Lit web component framework. Libraries like Lit are great for developing reusable web components that can be dropped in anywhere.

I also believe that Lit is a terrible choice for building Single Page Applications (SPAs). I believe this because once upon a time, I joined a team to work on a Lit SPA that had already been in development for over two years because things like routing had to be implemented from scratch and integrated with Lit. (There was much more nonsense involved that caused delays, but I'm choosing to leave that in the past 😉.)

One such problem we created in order to solve ourselves was the task of implementing modal windows. As useless as the work was for that specific project, the result was something worth holding onto and, with permission, publishing as an open source package on NPM, lit-modal-portal.

The portal Directive

The "portal" in "lit-modal-portal" comes from React's createPortal function, which takes as arguments both content and a target DOM node in which to render that content. In other words, portals are used to render a template somewhere else than where it is declared, and modals are one of many use cases.

Originally, my modal solution was a Lit component, but now it takes the form of an asynchronous directive named portal. To break this down:

• Directives (in Lit's terminology) are templating functions. They are loosely similar to "pipes" as defined in other frameworks including Angular and Hugo.

• Lit directives, like Lit components, can have their own lifecycle methods and state. This means that we don't need a separate component to manage the portal.

• Because Lit directives can be asynchronous, my portal directive can accept asynchronous content, as well as placeholder content to render until the primary content is resolved.

The implementation is rather simple, just about 75 lines of code with all comments and empty lines removed. I've included an edited version below:

import { render as litRender, nothing } from 'lit';
import { directive } from 'lit/directive.js';
import { AsyncDirective } from 'lit/async-directive.js';

export type TargetOrSelector = Node | string;
export interface PortalOptions {
  placeholder?: unknown;
}

function getTarget(targetOrSelector: TargetOrSelector): Node {
  let target = targetOrSelector;
  if (typeof target === 'string') {
    target = document.querySelector(target) as Node;
    if (target === null) {
      throw Error("Could not locate portal target.");
    }
  }
  return target;
}

export class PortalDirective extends AsyncDirective {
  private containerId = `portal-${self.crypto.randomUUID()}`;
  private container: HTMLElement | undefined;
  private target: Node | undefined;

  render(
    content: unknown | Promise<unknown>,
    targetOrSelector: TargetOrSelector | Promise<TargetOrSelector>,
    options?: PortalOptions,
  ) {
    Promise.resolve(targetOrSelector).then(async (targetOrSelector) => {
      if (!targetOrSelector) {
        throw Error("Target was falsy");
      }

      const newTarget = getTarget(targetOrSelector);
      if (!this.container) {
        const newContainer = document.createElement('div');
        newContainer.id = this.containerId;
        this.container = newContainer;
      }

      if (this.target && this.target !== newTarget) {
        this.target?.removeChild(this.container);
        newTarget.appendChild(this.container);
        this.target = newTarget;
      }

      if (!this.target) {
        this.target = newTarget;
        if (options?.placeholder) {
          if (!this.target.contains(this.container)) {
            this.target.appendChild(this.container);
          }
          litRender(options.placeholder, this.container);
        }
      }

      const resolvedContent = await Promise.resolve(content);
      if (!this.target.contains(this.container)) {
        this.target.appendChild(this.container);
      }
      litRender(resolvedContent, this.container);
    });

    return nothing;
  }
}

export const portal = directive(PortalDirective);

The directive will accept either a DOM node or a query selector string as the target for the portal. It will create a container <div>, append that container to the target, and then use Lit's render function to render the portal's content inside the container. I've aliased Lit's function as litRender to disambiguate it from the directive's own render method.

Documenting, Testing, and Demonstrating

Because this was to be the first bit of code I've ever published on a platform such as NPM, I wanted to ensure a high quality of life for the codebase. I made sure to add plenty of TypeDoc comments that would generate documentation I could host on GitHub Pages.

In the spirit of ✨web components✨, I followed Lit's advice and used Modern Web's test runner with the @open-wc/testing framework to add unit tests. My primary goal was to validate that the lifecycle methods of Lit components were triggered as expected even when they were rendered through a portal.

Finally, I wanted to enable anyone to experiment with the code as easily as possible. To that end, I put together a small demo webpage to show how the portal directive can be used. I combined this with Modern Web's dev server so that once you download the source code and install the dependencies, you can spin up the dev server, make any code changes you like, and immediately see the effects.