dialog-lite

dialog-lite

A small TypeScript library for controlling accessible modal dialogs with plain DOM markup.

Demo

---

Installation

npm install dialog-lite

---

Quick Start

import { initDialogLite } from 'dialog-lite'
import 'dialog-lite/dialog-lite.css'

const dialog = initDialogLite({
  closingButton: true,
  closingBackdrop: true,
  injectCss: false,
})

button.addEventListener('click', () => {
  dialog.open({ stylingClass: 'dialog-lite--result' })
})

Use hidden for the initial hidden state. Do not rely on style="display:none": the library toggles visibility through the hidden attribute.

<div class="dialog-lite dialog-lite--out" hidden aria-hidden="true">
  <div class="dialog-lite__backdrop"></div>
  <div class="dialog-lite__container">
    <div class="dialog-lite__container-inner">
      <button class="dialog-lite-close-button" type="button" aria-label="Close" tabindex="0">
        Close
      </button>
      <div>Your content</div>
    </div>
  </div>
</div>

---

API

• new DialogLite(options) — creates a controller instance.
• init() — resolves DOM elements and attaches event listeners.
• open(options) — opens the dialog, toggles classes and attributes, and moves focus inside.
• close() — closes the dialog, restores focus, and applies hidden after hideDelayMs.
• destroy() — removes listeners, clears timers, and unlocks scroll.
• isOpened() — returns the current controller open state.
• createDialogLite(options) — creates a controller without calling init().
• initDialogLite(options) — optionally injects CSS, calls init(), and returns a controller.
• injectDialogLiteCss(options) — injects the packaged CSS into document or a ShadowRoot.
• dialogLiteCssText — packaged minified CSS string, useful for Shadow DOM.

Options

Option	Type	Default	Description
closingButton	boolean	false	Enables close on .dialog-lite-close-button click.
closingBackdrop	boolean	false	Enables close on .dialog-lite__backdrop click.
dialog	HTMLElement | string	'.dialog-lite'	Dialog root element or selector.
mainContent	HTMLElement | string | null	'#main-content'	Element or selector to set aria-hidden on while open. Set null to disable.
closeButtonSelector	string	'.dialog-lite-close-button'	Close button selector inside the dialog.
backdropSelector	string	'.dialog-lite__backdrop'	Backdrop selector inside the dialog.
debounceMs	number	500	Debounce window for open() and close().
hideDelayMs	number	500	Delay before setting hidden on close. Should match CSS transitions.
focusOnOpenSelector	string	'[tabindex="0"]'	Element to focus when opened.
lockScroll	boolean	true	Locks page scroll while open.
trapFocus	boolean	true	Enables Tab cycling inside the dialog.
closeOnEscape	boolean	true	Enables closing the dialog with Escape.
role	string	'dialog'	Dialog role applied during init().
ariaModal	boolean	true	Sets aria-modal="true" during init().
emitEvents	boolean	true	Emits dialog-lite:open and dialog-lite:close.
onOpen	(detail) => void	-	Callback called after open().
onClose	(detail) => void	-	Callback called after close().

Events

• dialog-lite:open — dispatched on the dialog element after open(). event.detail includes { stylingClass }.
• dialog-lite:close — dispatched on the dialog element after close().

---

Vue 3

dialog-lite/vue provides a Vue-scoped composable and a component wrapper. Vue is an optional peer dependency, so the default dialog-lite entry remains framework-agnostic.

Import the CSS once in your app entry or global stylesheet:

import 'dialog-lite/dialog-lite.css'

Composable

Use useDialogLite() when you want to keep custom dialog markup.

<script setup lang="ts">
import { ref } from 'vue'
import { useDialogLite } from 'dialog-lite/vue'

const dialogRef = ref<HTMLElement | null>(null)
const { isOpen, open, close } = useDialogLite(dialogRef, {
  closingBackdrop: true,
  mainContent: null,
})
</script>

<template>
  <button type="button" @click="open({ stylingClass: 'dialog-lite--result' })">
    Open
  </button>

  <div ref="dialogRef" class="dialog-lite dialog-lite--out" hidden aria-hidden="true">
    <div class="dialog-lite__backdrop"></div>
    <div class="dialog-lite__container">
      <div class="dialog-lite__container-inner">
        <button type="button" @click="close">Close</button>
        <slot />
      </div>
    </div>
  </div>
</template>

useDialogLite() creates the controller in onMounted(), passes the Vue element ref to the core dialog option, keeps isOpen in sync through callbacks, and calls destroy() automatically when the component scope is disposed.

Component

Use DialogLiteRoot when you want the package to render the default BEM wrapper.

<script setup lang="ts">
import { computed, ref } from 'vue'
import { DialogLiteRoot } from 'dialog-lite/vue'

const result = ref<'won' | 'lost' | null>(null)
const isResultOpen = computed({
  get: () => result.value !== null,
  set: (value) => {
    if (!value) result.value = null
  },
})
</script>

<template>
  <DialogLiteRoot
    v-model="isResultOpen"
    :styling-class="result === 'won' ? 'dialog-lite--game-won' : 'dialog-lite--game-lost'"
    close-on-backdrop
    :main-content="null"
  >
    <GameWon v-if="result === 'won'" />
    <GameLost v-else @reset="isResultOpen = false" />
  </DialogLiteRoot>
</template>

Vue API

• useDialogLite(dialogRef, options) — creates a Vue-scoped controller, initializes it on mount, and destroys it on scope disposal.
• DialogLiteRoot — renders the default BEM markup and controls the core instance through v-model.
• DialogLiteRoot props — modelValue, stylingClass, closeOnBackdrop, closeOnButton, mainContent, debounceMs, hideDelayMs, lockScroll, trapFocus, closeOnEscape.
• DialogLiteRoot emits — update:modelValue, open, close.

For Nuxt or any SSR setup, import is safe but initialization is client-only. Use the composable or component inside mounted/client-rendered code, and wrap rendered dialogs in <ClientOnly> when the page is server-rendered.

---

Styling

The default stylesheet is available as a package subpath:

import 'dialog-lite/dialog-lite.css'

@import "dialog-lite/dialog-lite.css";

The default CSS uses BEM classes:

• .dialog-lite
• .dialog-lite--in
• .dialog-lite--out
• .dialog-lite__backdrop
• .dialog-lite__container
• .dialog-lite__container-inner
• .dialog-lite-close-button

The backdrop and z-index values can be customized with CSS variables:

• --z-index-dialog-lite
• --z-index-dialog-lite-backdrop
• --z-index-dialog-lite-container
• --c-dialog-lite-backdrop-in
• --c-dialog-lite-backdrop-out

---

License

MIT