# lit-modal-portal The `lit-modal-portal` package provides a [custom Lit directive](https://lit.dev/docs/templates/custom-directives/), `portal`, that renders a Lit template elsewhere in the DOM. Its main goals are: 1. to provide an API that is similar to React's [`createPortal`](https://react.dev/reference/react-dom/createPortal) function, and 2. to rely on the existing Lit API wherever possible. This package also supports _asynchronous_ portal content. > [!TIP] > This package is unfortunately stuck with the name `lit-modal-portal`. > > However, you may be better off with the standard behavior of the `` element if you wish to create a confirmation modal dialog or something like that. > See below for more information on [modals and dialogs](#modals-and-dialogs). ## Installation and Usage You can install `lit-modal-portal` via NPM. ``` npm install lit-modal-portal ``` Suppose we have the following Lit application: ```html lit-modal-portal Usage Example ``` ```js // index.ts (source code for main.js) import { LitElement, html } from 'lit'; import { customElement } from 'lit/decorators.js'; import { portal } from 'lit-modal-portal'; @customElement('app-root') export class AppRoot extends LitElement { render() { return html`

lit-modal-portal Usage Example

${portal(html`

portal content

`, document.body)} `; } } ``` When the `` component renders, it will activate the `portal` directive, which will return `nothing` but use Lit's API to asynchronously render the content in a container `
` and append that container to `document.body`. When the portal's content is updated, the directive will re-render the new content in the same container. Additionally, if the target changes, then the container will be removed from the old target and appended to the new target. ## API ```ts type TargetOrSelector = Node | string; type PortalOptions = { placeholder?: unknown; modifyContainer?: (container: HTMLElement) => void; }; portal( content: unknown | Promise, targetOrSelector: TargetOrSelector | Promise, options?: PortalOptions, ): DirectiveResult ``` Parameters: - `content`: The content of the portal. This parameter is passed as the `value` parameter in [Lit's `render` function](https://lit.dev/docs/api/templates/#render). > Any renderable value typically a [`TemplateResult`](https://lit.dev/docs/api/templates/#TemplateResult) > created by evaluating a template tag like [`html`](https://lit.dev/docs/api/templates/#html) or [`svg`](https://lit.dev/docs/api/templates/#svg). - `targetOrSelector`: An element or a string that identifies the portal's target. If the value is a string, then it is treated as a query selector and passed to `document.querySelector()` in order to locate the portal target. If no element is found with the selector, then an error is thrown. - `options`: Configuration parameters for the portal. - `placeholder`: A value that will be rendered while the `content` is resolving. - `modifyContainer`: A function that will be called with the portal's container provided as an argument. This allows you to programmatically control the container before the portal renders. This function will always return [Lit's `nothing` value](https://lit.dev/docs/api/templates/#nothing), because nothing is supposed to render where the portal is used. Both the `content` and the `targetOrSelector` parameters may be promises. The `targetOrSelector` must resolve before the portal renders. If the `content` is a promise, then an optional `placeholder` may be provided. If no `placeholder` is provided, then the portal will not render until the `content` resolves. See [the docs](https://nicholas-wilcox.github.io/lit-modal-portal/classes/PortalDirective.html#render) for more information on how the `portal` directive works. ## Advanced Usage ### Modals and Dialogs Modals are a long dicussed topic in web development. One recommended approach is to use the [`dialog`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element and its [`showModal`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/showModal) method, which can be accessed using [Lit's `ref` directive](https://lit.dev/docs/templates/directives/#referencing-rendered-dom). Consider the following: ```ts // example-app.ts import { LitElement, html } from 'lit'; import { customElement } from 'lit/decorators.js'; import { ref, createRef } from 'lit/directives/ref.js'; @customElement('example-app') export class ExampleApp extends LitElement { dialogRef = createRef(); render() { return html`

lit-modal-portal Dialog Example

This is the dialog

 `; } } ``` In this example, we have a component with a `dialogRef` attached to a `` element. This allows the app to imperatively open and close the dialog on a button's `@click` event. > [!NOTE] > This example does not use the `lit-modal-portal` package. You should consider if a package such as this is necessary for your use case, as you might be better off with the standard `` behavior. This basic pattern can be extended as necessary. Examples include: - Listening to the dialog's `close` event, which would trigger if the dialog was closed with the Escape key or with the "Close Dialog" button. - Adding styles to the `` element. - Creating a separate Lit component to manage tie `` element. ### Targeting elements in the Shadow DOM Using a DOM node in a Lit component as a target for a portal is tricky (and perhaps useless or inadvisable), for a number of reasons: 1. The `querySelector` method does not penetrate through the shadow root, so running queries on the `document` node won't return anything. 2. The `portal` directive is _asynchronous_, so if it renders at the same time as the component's first render, _then the target might not even exist yet_. We cannot simply call `querySelector` on a different render root, such as a component's shadow root, because it might be empty. However, this is still possible to accomplish safely with the use of [Lit's `queryAsync` decorator](https://lit.dev/docs/api/decorators/#queryAsync). ```ts import { LitElement, html } from 'lit'; import { customElement, queryAsync } from 'lit/decorators.js'; import { portal } from 'lit-modal-portal'; @customElement('example-component') export class ExampleComponent extends LitElement { @queryAsync('#portal-target') portalTarget: Promise; render() { return html`
${portal(html`

Portal content

`, this.portalTarget)}

The portal isn't rendered before this paragraph, but in the following div.

`; } } ``` In this example, `this.portalTarget` is a promise that resolves to the `