Dialog

Basic Usage

Create dialogs using the k-dialog component. Open the dialog by calling the open() method, and close it by calling the close() method. Or it can be closed using the dialog's GUI (clicking the overlay, clicking the close button, or the cancel or confirm action buttons).

<k-dialog id="d1">
  <p class="p">Hello World</p>
</k-dialog>
<button onclick="document.getElementById('d1').open()">Open Dialog</button>

Titles

Assign an element to the title slot to have it appear as the dialog title.

<k-dialog id="d2">
  <h6
    class="m0 px"
    slot="title"
  >This is a fact</h6>
  <p class="p">A hotdog is a sandwhich</p>
</k-dialog>

Action Buttons

Add a cancel button using the cancel-text attribute.

<k-dialog
  id="d4"
  cancel-text="Absolutly Not"
>
  <p class="p">Mint and Chocolate belong together</p>
</k-dialog>

Add a confirm button using the confirm-text attribute.

<k-dialog
  id="d5"
  confirm-text="Confirm"
>
  <p class="p">Spaghetti is the greatest food</p>
</k-dialog>

Try it with both a cancel and confirm button.

<k-dialog
  id="d6"
  cancel-text="It should be outlawed"
  confirm-text="Of course it is"
>
  <p class="p">Ranch is gross</p>
</k-dialog>

Disabling Keyboard Close

You can disable closing the dialog with the ESC key by adding the disable-keyboard-close attribute. This is useful for dialogs that require explicit user action.

<k-dialog id="d10" disable-keyboard-close>
  <p class="p">This dialog cannot be closed with ESC</p>
</k-dialog>
<button onclick="document.getElementById('d10').open()">Open Dialog</button>

JavaScript Usage

Create Dialog

<button id="d7">Open Dialog</button>
<script type="module">
  import Dialog from '/src/components/Dialog.js';
  document.getElementById('d7').addEventListener('click', () => {
    Dialog.create('Hello World');
  });
</script>

Dialog with Title

<button id="d7b">Open Dialog with Title</button>
<script type="module">
  import Dialog from '/src/components/Dialog.js';
  document.getElementById('d7b').addEventListener('click', () => {
    Dialog.create('This is the dialog content', {
      title: 'My Dialog Title'
    });
  });
</script>

Error Dialog

<button id="d8">Open Dialog</button>
<script type="module">
  import Dialog from '/src/components/Dialog.js';
  document.getElementById('d8').addEventListener('click', () => {
    Dialog.error("Oh no, don't do that!");
  });
</script>

Lit Template Content

You can pass a Lit html tagged template literal directly as the content to any of the static methods (Dialog.create, Dialog.confirm, Dialog.alert, Dialog.error, Dialog.success).

<button id="d11">Open Dialog with Lit Template</button>
<script type="module">
  import Dialog from '/src/components/Dialog.js';
  import { html } from '/src/lit-all.min.js';
  document.getElementById('d11').addEventListener('click', () => {
    Dialog.create(html`
      <div class="p">
        <h6>Custom Lit Content</h6>
        <p>This was created with a Lit template.</p>
      </div>
    `, {
      title: 'Lit Template Dialog'
    });
  });
</script>

Confirm Dialog

Use the Dialog.confirm static method to create a confirmation dialog. This method takes a text message, a response callback, and an options object.

<button id="d9">Open Confirm Dialog</button>
<script type="module">
  import Dialog from '/src/components/Dialog.js';
  document.getElementById('d9').addEventListener('click', () => {
    Dialog.confirm("Are you sure you want to proceed?", response => {
      console.log("User response:", response);
    });
  });
</script>

JavaScript Reference

Constructor

Extends ShadowComponent

new Dialog()
new Dialog(object options)

Parameters

options: object

An object containing the initial configuration for the dialog. The options object can contain the following properties:

• opened: boolean - Whether the dialog is initially opened.
• closeBtn: boolean - Whether to show the close button.
• overlayClose: boolean - Whether clicking the overlay closes the dialog.
• confirmText: string - Text for the confirm button.
• confirmClasses: string - Classes for the confirm button.
• confirmAction: function - Action to perform on confirm.
• cancelText: string - Text for the cancel button.
• cancelClasses: string - Classes for the cancel button.
• cancelAction: function - Action to perform on cancel.
• closeCallback: function - Callback to execute when the dialog is closed.

Requirements

• ShadowComponent
• Icon
• FocusCapture

Attributes

opened: boolean

Whether the dialog is opened.

close-btn: boolean

Whether to show the close button. Default is true.

overlay-close: boolean

Whether clicking the overlay closes the dialog. Default is true.

disable-keyboard-close: boolean

Whether to disable closing the dialog with the ESC key. Default is false.

confirm-text: string

Text for the confirm button.

confirm-classes: string

Classes for the confirm button. Default is 'success ml'.

cancel-text: string

Text for the cancel button.

cancel-classes: string

Classes for the cancel button.

Properties

confirmAction: function

Action to perform on confirm. If the function calls event.preventDefault(), the dialog will not close automatically.

cancelAction: function

Action to perform on cancel. If the function calls event.preventDefault(), the dialog will not close automatically.

disableKeyboardClose: boolean

Whether to disable closing the dialog with the ESC key. Default is false.

closeCallback: function

Callback to execute when the dialog is closed.

previousFocus: HTMLElement

Reference to the element that had focus before the dialog was opened.

Methods

open(): void

Opens the dialog and sets focus to the first focusable element or an element with the autofocus attribute.

close(): void

Closes the dialog and calls the closeCallback.

toggle(): void

Toggles the dialog open or closed.

focus(): void

Focuses the first focusable element in the dialog and saves the previously focused element.

blur(): void

Returns focus to the element that had focus before the dialog was opened.

Static Methods

Dialog.create(contents, options): Dialog

Creates and opens a new dialog with the specified contents and options. Returns the created Dialog instance.

If contents is plain text (no HTML tags), it will automatically be wrapped in a <p class="p"> tag. If it contains HTML, it will be inserted as-is. If it's an HTMLElement or DocumentFragment, it will be appended directly. You can also pass a Lit html tagged template literal (TemplateResult), which will be rendered using Lit's render().

Parameters

• contents: string | HTMLElement | DocumentFragment | TemplateResult - The content to display in the dialog. Plain text will be wrapped in a paragraph tag automatically.
• options: object - Configuration options for the dialog.

Options

• title: string | HTMLElement - The title to display in the dialog header. Will be wrapped in an <h5> tag with the title slot.
• titleClasses: string - CSS classes for the title element. Default is 'pyh px m0'.
• opened: boolean - Whether the dialog is initially opened. Default is true.
• closeBtn: boolean - Whether to show the close button.
• overlayClose: boolean - Whether clicking the overlay closes the dialog.
• disableKeyboardClose: boolean - Whether to disable closing the dialog with the ESC key.
• confirmText: string - Text for the confirm button.
• confirmClasses: string - Classes for the confirm button.
• confirmAction: function - Action to perform on confirm.
• cancelText: string - Text for the cancel button.
• cancelClasses: string - Classes for the cancel button.
• cancelAction: function - Action to perform on cancel.
• closeCallback: function - Callback to execute when the dialog is closed.
• removeOnClose: boolean - Whether to remove the dialog from the DOM when closed. Default is true.
• closeExisting: boolean - Whether to close existing dialogs before opening this one. Default is true.
• width: string - CSS width value for the dialog.
• minWidth: string - CSS min-width value for the dialog.
• maxWidth: string - CSS max-width value for the dialog.
• height: string - CSS height value for the dialog.
• minHeight: string - CSS min-height value for the dialog.
• maxHeight: string - CSS max-height value for the dialog.

Dialog.confirm(text, responseCallback, options): Dialog

Creates and opens a confirmation dialog with the specified text and options. The response callback receives a boolean value indicating whether the user confirmed (true) or canceled (false). By default, the close button and overlay close are disabled, and keyboard close (ESC key) is disabled to ensure the user must explicitly choose Yes or No.

Parameters

• text: string | TemplateResult - The message to display in the dialog.
• responseCallback: function - Function called with the user's response (true for confirm, false for cancel).
• options: object - Configuration options.

Options

• title: string - The title of the dialog. Default is 'Confirm'.
• confirmText: string - Text for the confirm button. Default is 'Yes'.
• confirmClasses: string - Classes for the confirm button. Default is 'success ml'.
• cancelText: string - Text for the cancel button. Default is 'No'.
• cancelClasses: string - Classes for the cancel button. Default is 'danger'.
• closeBtn: boolean - Whether to show the close button. Default is false.
• overlayClose: boolean - Whether clicking the overlay closes the dialog. Default is false.
• disableKeyboardClose: boolean - Whether to disable closing the dialog with the ESC key. Default is true.

Dialog.alert(text, responseCallback, options): Dialog

Creates and opens an alert dialog with the specified text and options.

Parameters

• text: string | TemplateResult - The message to display in the dialog.
• responseCallback: function - Function called when the dialog is closed.
• options: object - Configuration options.

Options

• title: string - The title of the dialog. Default is 'Alert'.
• cancelText: string - Text for the OK button. Default is 'Ok'.

Dialog.error(text, responseCallback, options): Dialog

Creates and opens an error dialog with the specified text and options. The title is displayed in red.

Parameters

• text: string | TemplateResult - The error message to display in the dialog.
• responseCallback: function - Function called when the dialog is closed.
• options: object - Configuration options.

Options

• title: string - The title of the dialog. Default is 'Error'.
• cancelText: string - Text for the OK button. Default is 'Ok'.

Dialog.success(text, responseCallback, options): Dialog

Creates and opens a success dialog with the specified text and options. The title is displayed in green.

Parameters

• text: string | TemplateResult - The success message to display in the dialog.
• responseCallback: function - Function called when the dialog is closed.
• options: object - Configuration options.

Options

• title: string - The title of the dialog. Default is 'Success'.
• cancelText: string - Text for the OK button. Default is 'Ok'.