Documentation

Getting Started

kmodals is a lightweight, event-driven browser modal library with promise-based helpers, responsive dialog, sheet and drawer presentations, and accessible focus management. The distributed browser builds are self-contained and include their styles.

npm install ./path/to/kmodals

import kmodal from 'kmodals';

<script src="/assets/kmodals.umd.js"></script>

import kmodal from './vendor/kmodals.es.js';

Basic Usage

// Using constructor with content and options
const myModal = new kmodal('Hello World!', {
  type: 'info',
  header: 'Welcome'
});

// Using constructor with a single options object
new kmodal({
  header: 'Alert',
  content: 'Something happened!',
  type: 'alert'
});

// Using static confirm (Promise<boolean>)
const accepted = await kmodal.confirm('Are you sure?');
if (accepted) {
  // do something
}

Options API

Pass as the second argument to the kmodal constructor or the static helpers.

Properties

• element: HTMLElement | null — Root DOM element of the modal (read-only)

Instance Methods

• show(): Promise<void> — Displays the modal
• hide(): Promise<void> — Hides the modal
• setContent(content: string): void — Updates body content
• setHeader(content: string): void — Updates header content
• setIcon(type: 'info' | 'alert' | 'confirm' | 'error' | 'loading' | 'prompt' | 'clean'): void — Changes the modal icon
• setOption<K extends keyof KModalOptions>(key: K, value: KModalOptions[K]): void — Updates an option and refreshes UI

Static Methods

Convenient shortcuts that return a Promise (except for loading).

• kmodal.info(content, options?): Promise<void>
• kmodal.alert(content, options?): Promise<void>
• kmodal.error(content, options?): Promise<void>
• kmodal.confirm(content, options?): Promise<boolean>
• kmodal.prompt(content, options?): Promise<string | null>
• kmodal.loading(content, options?): kmodal — returns the instance
• kmodal.setDefaults(options: Partial<KModalOptions>): void — Sets global defaults
• kmodal.resetDefaults(): void — Resets global defaults

Events

kmodals uses standard CustomEvent. All events receive CustomEvent object as an argument. The modal instance is available in event.detail.instance.

const modal = new kmodal('Check console');

// Using event listener
modal.addEventListener('show', (event) => {
  console.log('Modal instance:', event.detail.instance);
  console.log('Modal is fully visible!');
});

// Preventing closure
modal.addEventListener('buttonOneClick', (event) => {
  if (someCondition) {
    event.preventDefault(); // stops the modal from hiding
  }
});

Callback Wrappers

You can pass these callbacks directly in the options object. Callback wrappers receive instance and CustomEvent object as arguments.

new kmodal('Hello!', {
  onShow: (instance, event) => {
    console.log('Modal is visible!', event.detail.instance, event);
  },
  onButtonOneClick: (instance, event) => {
    console.log('Button clicked!');
    // event.preventDefault(); // You can also prevent default here
  }
});

Advanced Examples

Form with Validation

const formContent = `
  <form id="my-form">
    <label>Name:</label>
    <input type="text" id="name" required class="w-full mt-1 border rounded px-2 py-1">
    <p id="error-msg" class="text-red-600 hidden">Name is required!</p>
  </form>`;

const modal = new kmodal(formContent, {
  header: 'User Info',
  buttonOneText: 'Save',
  onButtonOneClick: (instance, event) => {
    const nameInput = document.getElementById('name');
    if (!nameInput.value) {
      event.preventDefault(); // Stop modal from closing
      document.getElementById('error-msg').classList.remove('hidden');
    } else {
      console.log('Form submitted:', nameInput.value);
    }
  }
});

Custom Multi‑Step Modal

let step = 1;
const modal = new kmodal('Step 1: Welcome!', {
  buttonOneText: 'Next',
  onButtonOneClick: (instance, event) => {
    if (step === 1) {
      event.preventDefault(); // Stay open
      instance.setContent('Step 2: Almost done.');
      instance.setOption('buttonOneText', 'Finish');
      step = 2;
    }
  }
});

Persistent Loading

const loader = kmodal.loading('Processing data...');

// Simulate async task
setTimeout(() => {
  loader.hide();
  kmodal.info('Data processed successfully!');
}, 3000);

Layouts, Placement and Motion

Use dialog for a conventional centered surface, sheet for an edge panel that is usually anchored to the bottom, and drawer for a tall side panel. Placement and motion are independent and validated at runtime.

new kmodal('Review the details.', {
  header: 'Order summary',
  presentation: 'dialog',
  motion: 'slide',
  responsive: {
    breakpoint: 768,
    presentation: 'sheet',
    placement: 'bottom',
    density: 'compact'
  }
});

new kmodal('Account settings', {
  header: 'Settings',
  presentation: 'drawer',
  placement: 'end',
  motion: 'slide',
  showCloseButton: true
});

fade changes opacity, scale grows a centered surface, slide enters from the effective edge, spring adds a shorter overshooting movement, and none disables the transition. Reduced-motion preferences suppress animated transforms automatically.

Themes

Built‑in themes: light, dark, glass, editorial, and contrast. By default, auto follows the system preference.

new kmodal('Glass Style', { theme: 'glass' });

Button Variants

Append a variant to change the primary button color:

• primary, info, success, warning, danger, darky

new kmodal('Delete account?', { theme: 'light danger' });

CSS Customization

You can easily customize kmodals using CSS variables. Define them in your :root or a specific scope.

Compatibility aliases such as --kmodal-btn-primary and --kmodal-border-radius remain available, but new themes should prefer the semantic tokens above.

.kmodal-brand {
  --kmodal-accent: #10b981;
  --kmodal-radius: 8px;
  --kmodal-width: 36rem;
}

Accessibility and Security

kmodals provides dialog semantics, accessible labelling, focus trapping and restoration, top-modal keyboard handling, stacked-modal coordination, background isolation, reduced-motion behavior, and forced-colors support. Applications remain responsible for meaningful headings, explicit action labels, appropriate initial focus, and accessible custom HTML.

new kmodal(untrustedHtml, {
  header: 'Preview',
  sanitizeContent: true,
  sanitizeAllowedTags: ['p', 'strong', 'em', 'a', 'br']
});

Framework Integration

kmodals is framework-independent and mounts under document.body. Create instances only from client-side lifecycle code. For one-shot interactions, use the static promise helpers. If a component may unmount while a modal remains open, keep the returned instance and call hide() during cleanup. Do not construct a modal during server rendering, where document is unavailable.

Localization

By default, kmodals uses English labels (Accept, Cancel). You can easily override these per instance using the buttonOneText and buttonTwoText options.

new kmodal('Are you sure?', {
  buttonOneText: 'Yes, proceed',
  buttonTwoText: 'No, cancel'
});

Global Configuration

You can set global defaults for all modal instances in two ways:

1. Using JavaScript

kmodal.setDefaults({
  theme: 'light',
  buttonOneText: 'OK',
  buttonTwoText: 'Cancel'
});

2. Using Data Attributes

When using the UMD version, you can provide defaults directly on the script tag:

<script 
  src="./kmodals.umd.js" 
  data-theme="glass" 
  data-button-one-text="Accept">
</script>

Note: For boolean values use "true"/"false". For type option use data-default-type.

Changelog

Version 4.0.0

• Dialog, sheet, and drawer presentations with responsive overrides
• Light, dark, glass, editorial, contrast, and automatic themes
• Configurable placement, motion, density, and destructive confirmations
• Accessible focus management and DOMPurify-backed HTML sanitization
• ES module, UMD, and TypeScript declaration builds