Overlays

Dialog

A modal dialog built on the native <dialog>. Focus stays inside, Escape closes it, and the rest of the page goes inert — the platform does the heavy lifting.

Element: <slab-dialog>
Built on: <dialog> (modal)
As Markdown: dialog.md

Example

Here's a styled version, <slab-styled-dialog>. It's not in the package — it's an example of what you can build with the headless element. Copy it and make it yours at the bottom of this page. Switch to "As it ships" to see the same markup with the headless element and no CSS at all. That's your starting point.

Styled example

As it ships

It's day 2 of 7. Concrete reaches about 70% of its strength in a week, and stripping the forms now can crack the edges.

HTML

<button class="styled-button styled-button--danger" type="button">
  Strip forms
</button>

<slab-styled-dialog id="dialog-example" label="Strip the forms?" closedby="any">
  <p>
    It's day 2 of 7. Concrete reaches about 70% of its strength in a week,
    and stripping the forms now can crack the edges.
  </p>

  <form class="actions" method="dialog">
    <button class="styled-button" value="cancel">Wait</button>
    <button class="styled-button styled-button--danger" value="strip">Strip anyway</button>
  </form>
</slab-styled-dialog>

It's day 2 of 7. Concrete reaches about 70% of its strength in a week, and stripping the forms now can crack the edges.

HTML

<button class="styled-button styled-button--danger" type="button">
  Strip forms
</button>

<slab-dialog id="dialog-example-as-it-ships" label="Strip the forms?" closedby="any">
  <p>
    It's day 2 of 7. Concrete reaches about 70% of its strength in a week,
    and stripping the forms now can crack the edges.
  </p>

  <form class="actions" method="dialog">
    <button class="styled-button" value="cancel">Wait</button>
    <button class="styled-button styled-button--danger" value="strip">Strip anyway</button>
  </form>
</slab-dialog>

Usage

Install

pnpm add slab-elements lit

HTML

<script type="module">
  import 'slab-elements/dialog.js';
</script>

<slab-dialog label="Delete this file?">
  <p>It can't be recovered.</p>

  <form method="dialog">
    <button value="cancel">Cancel</button>
    <button value="delete">Delete</button>
  </form>
</slab-dialog>

Open it by setting open. When it closes, returnValue tells you which button did it — same as a <dialog>.

Keyboard

Key	What it does
Tab, Shift+Tab	Moves focus between the dialog’s controls. The rest of the page is inert.
Escape	Closes the dialog and dispatches “cancel”, which can be canceled to keep it open.

Behavior

A modal dialog with no visual styles, around a native <dialog> opened with showModal(), so it traps focus, closes on Escape, has a ::backdrop, and makes the rest of the page inert the way one does.

open reflects, and it stays true to the dialog: when the dialog closes itself, on Escape or through a <form method="dialog">, open goes false along with it. close(returnValue) and a <form method="dialog">'s submitter both set returnValue, as they do on a <dialog>.

The dialog is named by its label: the label attribute or the label slot. The label isn't a heading, because a heading's level is the page's to choose. Plain label text names the dialog without being one. For a heading, slot your own at whatever level fits: <h2 slot="label">.

Light dismiss is the platform's or nothing. closedby="any" is passed through to the <dialog>, which closes on a backdrop click where the browser supports it and ignores the attribute where it doesn't. Nothing here listens for clicks on the backdrop to fake it.

Style it through its parts, and the backdrop through ::part(dialog)::backdrop.

API

`<slab-dialog>`

Attributes
Name	Type	Default	Description
`closedby`	`'any' \| 'closerequest' \| 'none'`		Passed to the `<dialog>`. "any" closes it on a click outside it where the browser supports that. Browsers that don't ignore it.
`hide-label`	`boolean`	`false`
`label`	`string`
`open`	`boolean`	`false`
`version`	`string`

Properties
Name	Type	Description
`returnValue`	`string`	The `<dialog>`'s, so `close(returnValue)` and a `<form method="dialog">` set it the way they do natively.

Methods
Signature	Description
`close(returnValue?: string): void`
`show(): void`

Events
Name	Type	Description
`cancel`	`Event`
`close`	`Event`

Slots
Name	Type	Description
`label`	`Element \| string`
`(default)`	`Element \| string`

CSS parts
Name	Description
`dialog`	The native dialog. A modal one's backdrop is its ::backdrop
`label`	The label

Copy and own it

<slab-styled-dialog> isn't in the package. It's an example — copy it into your project and change whatever you want. Under the hood, it's just the headless element, subclassed, with styles set. That's it. Keyboard, focus, ARIA, forms, and events all come from the headless element, and the styles only reach in through ::part() and :state(), same as yours would.

To use it, copy these files, swap the tag in @customElement() for one of your own, and import it. tokens.styles.ts holds the colors and fonts every styled example shares, so you only need it once.

TypeScript

These files are TypeScript, and @customElement() is one of Lit's decorators (TypeScript's experimental flavor). You'll need two options in your tsconfig, per Lit's docs: experimentalDecorators to compile them, and useDefineForClassFields turned off so class fields don't stomp on the accessors Lit sets up.

tsconfig.json

{
  "compilerOptions": {
    "experimentalDecorators": true,
    "useDefineForClassFields": false
  }
}

Using plain JavaScript? Drop the types and register the class with customElements.define() instead of the decorator.

dialog.ts

import { customElement } from 'lit/decorators.js';
import Dialog from 'slab-elements/dialog.js';
import styles from './dialog.styles.js';
import tokens from './tokens.styles.js';

declare global {
  interface HTMLElementTagNameMap {
    'slab-styled-dialog': StyledDialog;
  }
}

/**
 * Dialog, styled: a paper slab under an ink header with an ember base, casting
 * an ember shadow over a dimmed page.
 */
@customElement('slab-styled-dialog')
export default class StyledDialog extends Dialog {
  static override styles = [tokens, styles];
}

dialog.styles.ts

import { css } from 'lit';

export default css`
  /*
    A closed dialog isn't displayed, so the animation runs again each time it
    opens.
  */
  [part~='dialog'] {
    animation: rise 200ms ease-out;
    background-color: var(--paper);
    border: 3px solid var(--ink);
    box-shadow: 10px 10px 0 var(--ember);
    box-sizing: border-box;
    color: var(--ink);
    font-family: var(--font-body);
    inline-size: min(32rem, 100% - 2rem);
    line-height: 1.5;
    padding: 0 1.5rem 1.5rem;

    &::backdrop {
      animation: fade 200ms ease-out;

      /*
        Not a token. A backdrop doesn't inherit custom properties from the
        dialog in every browser, but it does take its color scheme.
      */
      background-color: light-dark(rgb(28 28 28 / 70%), rgb(0 0 0 / 75%));
    }
  }

  /*
    The header. It's pulled out to the dialog's edges, which its padding would
    otherwise keep it from.
  */
  [part~='label'] {
    /*
      Ink in the light. In the dark, ink is the light color, so the header is
      the raised surface instead, rather than a bright bar.
    */
    background-color: light-dark(var(--ink), var(--chalk));
    border-block-end: 6px solid var(--ember);
    color: light-dark(var(--paper), var(--ink));
    font-family: var(--font-display);
    font-size: 1.5rem;
    font-weight: 600;
    margin-block-end: 1.25rem;
    margin-inline: -1.5rem;
    padding: 1rem 1.5rem;
  }

  @keyframes rise {
    from {
      opacity: 0;
      translate: 0 1rem;
    }
  }

  @keyframes fade {
    from {
      opacity: 0;
    }
  }

  @media (prefers-reduced-motion: reduce) {
    [part~='dialog'],
    [part~='dialog']::backdrop {
      animation: none;
    }
  }
`;

tokens.styles.ts

import { css } from 'lit';

/*
  The styled components' palette and type, taken from the logo: ink for the
  courses, ember for the base, paper behind them.

  Each is a short alias for a "--slab-styled-*" property, with the default as
  its fallback. Retheming is "--slab-styled-ember" and the rest on ":root",
  which every shadow root inherits. Were the defaults declared under those
  names here instead, each host's own declaration would shadow the page's.

  Each default is "light-dark()", so the components follow the page's
  "color-scheme": "dark" for dark, "light" for light, and "light dark" to
  follow the operating system. Ink and paper trade places in the dark, so
  ink is always the text and paper always what's behind it. Contrast is given
  as light, then dark.
*/
export default css`
  :host {
    /* Secondary text. 6.8:1 and 6.9:1 on paper. */
    --ash: var(--slab-styled-ash, light-dark(#5e5a55, #a8a19a));
    --border: 2px solid var(--ink);

    /* Behind disabled and read-only controls, and hovered rows. */
    --chalk: var(--slab-styled-chalk, light-dark(#f4f1ec, #2b2926));

    /*
      The logo's orange, brighter in the dark. 4.25:1 and 5.2:1 on paper is
      enough for borders, fills and large text, but not always for small text,
      which takes "--ember-deep".
    */
    --ember: var(--slab-styled-ember, light-dark(#d9492a, #ec5f3b));

    /*
      Orange for small text on paper, and for paper text on it. 5.7:1 and
      7.4:1.
    */
    --ember-deep: var(--slab-styled-ember-deep, light-dark(#b3381a, #ff8566));
    --font-body: var(
      --slab-styled-font-body,
      'IBM Plex Sans',
      system-ui,
      sans-serif
    );
    --font-display: var(
      --slab-styled-font-display,
      'Zilla Slab',
      rockwell,
      'Roboto Slab',
      serif
    );
    --font-mono: var(
      --slab-styled-font-mono,
      'IBM Plex Mono',
      ui-monospace,
      monospace
    );
    --ink: var(--slab-styled-ink, light-dark(#1c1c1c, #f4f1ec));
    --paper: var(--slab-styled-paper, light-dark(#fff, #1a1918));

    /* The hard, offset shadow a raised surface casts. */
    --shadow: 4px 4px 0 var(--ink);
  }
`;