@outbook/webcomponents-modal-dialog

This package provides a modal dialog component with two built-in layouts:

• content: full-screen content dialog
• message: centered message dialog with veil

The package is intended to be used through the ModalDialog() wrapper, which creates, renders, and removes the dialog for you.

Installation

npm install @outbook/webcomponents-modal-dialog

Usage

Content Dialog

import { html } from 'lit';
import { ModalDialog } from '@outbook/webcomponents-modal-dialog';

function openExampleModal(ev) {
  ModalDialog({
    origin: ev.currentTarget.id,
    title: 'Example modal',
    type: 'content',
    view: ({ closeDialog }) => html`
      <p>This is the content of the modal dialog.</p>
      <button @click="${closeDialog}">Close</button>
    `
  });
}

function render() {
  return html`
    <button id="open-modal" @click="${openExampleModal}">Open modal</button>
  `;
}

Message Dialog With Actions

import { html } from 'lit';
import { ModalDialog } from '@outbook/webcomponents-modal-dialog';

const saveAction = ({ detail }) => {
  console.log('button interaction:', detail.originalEvent.type);
};

function openMessageModal(ev) {
  ModalDialog({
    origin: ev.currentTarget.id,
    title: 'Confirm action',
    type: 'message',
    view: () => html` <p>Do you want to save your changes?</p> `,
    actions: [
      {
        text: 'Save',
        type: 'positive',
        eventFn: saveAction
      },
      {
        text: 'Cancel',
        type: 'neutral',
        handler: 'close'
      }
    ]
  });
}

API

ModalDialog(props)

Creates and renders an outbook-modal-dialog.

| Property | Type | Default | Description | | ----------------- | ---------- | ----------- | -------------------------------------------------------------------------------------------------------- | | origin | String | undefined | Id of the element that opened the dialog. Focus is returned to this element when the dialog closes. | | title | String | undefined | Dialog title shown in the header. | | type | String | 'content' | Dialog layout. Supported values are 'content' and 'message'. | | view | Function | null | Function that returns the dialog body. Receives { closeDialog }. | | tabs | Array | [] | Tab configuration passed to @outbook/webcomponents-tabs. If present, it is rendered instead of view. | | hasScroll | Boolean | true | Enables scrolling for content dialogs. Ignored for message dialogs and for dialogs with tabs. | | actions | Array | [] | Footer button configuration. | | portalWrapperId | String | null | Optional container element id for rendering the dialog portal. Defaults to document.body. | | content | Function | undefined | Optional fallback slot content renderer used internally by the component. |

actions

Each action item supports the following properties:

| Property | Type | Default | Description | | --------- | ---------- | ----------- | --------------------------------------------------------------------------------- | | text | String | undefined | Button label. | | type | String | 'neutral' | Visual variant. Supported values are 'neutral', 'positive', and 'negative'. | | handler | String | undefined | Name of an internal dialog handler. Currently close is supported. | | eventFn | Function | () => {} | Handler for the button button-interaction event when no handler is defined. |

Action handler resolution order:

1. handlers[handler]
2. eventFn
3. empty function

When handler: 'close' is used, the dialog closes and focus returns to origin.

Component

outbook-modal-dialog

This is the underlying custom element used by ModalDialog(). It is not usually instantiated directly, because the wrapper manages portal rendering, lifecycle, keyboard handling, and focus return.

Styling

The component uses Shadow DOM and exposes styling hooks through CSS custom properties.

Custom Properties

| Custom Property | Description | | --------------------------------------------------- | -------------------------------------------------------- | | --outbook-modal-dialog--veil-color | Veil color behind the dialog. Used by message dialogs. | | --outbook-modal-dialog--neutral-background | Background color for neutral action buttons. | | --outbook-modal-dialog--neutral-background-hover | Hover background color for neutral action buttons. | | --outbook-modal-dialog--positive-background | Background color for positive action buttons. | | --outbook-modal-dialog--positive-background-hover | Hover background color for positive action buttons. | | --outbook-modal-dialog--negative-background | Background color for negative action buttons. | | --outbook-modal-dialog--negative-background-hover | Hover background color for negative action buttons. |

The dialog also forwards --outbook-scrollable--indicator-max-width internally for the scrollable content area.

Notes

• type: 'content' renders a full-screen dialog layout.
• type: 'message' renders a centered dialog with a veil overlay.
• The close button responds to mouse click, Enter, and Space.
• Escape closes the dialog.

License

This component is licensed under the Apache-2.0 License.