API reference

Installation

Install from npm. The package name is one word; the library is called Forge Dialog.

npm install forgedialog

Import the API and a stylesheet:

import { alert, confirm, prompt, open } from 'forgedialog';
import 'forgedialog/style.css';

Or load the browser build directly. It defines the global ForgeDialog — a JavaScript identifier, so it stays one word.

<link rel="stylesheet" href="https://unpkg.com/forgedialog/dist/index.css" />
<script src="https://unpkg.com/forgedialog/dist/index.global.js"></script>
<script>
  ForgeDialog.alert('Hello!');
</script>

Requires Chrome/Edge 88+, Firefox 78+, Safari 15.4+, or Node.js 20+ for package tooling and server-side imports.

Entry points

Every entry point is tree-shakable and has its own gzip budget enforced in CI. Import the narrowest one that covers what you need.

Capability imports

The single-purpose entries (/alert, /confirm, /prompt) ship a lightweight appearance applier covering surface opacity, backdrop, border, and shadow presets. Add capabilities by importing them for their side effect:

import 'forgedialog/appearance';   // per-component colour, radius, hover
import 'forgedialog/interactions'; // dragging
import 'forgedialog/animations';   // animation presets
import { alert } from 'forgedialog/alert';

forgedialog and forgedialog/core already include the full appearance applier, so those imports are only needed alongside a focused entry.

Stylesheets

forgedialog/style.css is the all-in-one sheet. To ship less CSS, compose only the layers a page uses — core.css is always required.

import 'forgedialog/style/core.css';      // required
import 'forgedialog/style/forms.css';     // form fields and file dropzones
import 'forgedialog/style/workflows.css'; // wizard stepper
import 'forgedialog/style/toast.css';
import 'forgedialog/style/lightbox.css';
import 'forgedialog/style/command.css';
import 'forgedialog/style/draggable.css';

All rules live in the forgedialog cascade layer, so your own unlayered CSS wins without needing !important.

alert, confirm, prompt

Promise-returning replacements for the browser built-ins.

await alert('Saved successfully.', { title: 'Success' });

const ok = await confirm('Delete this item?', { title: 'Please confirm' });

const name = await prompt('What is your name?', {
  defaultValue: 'Ada Lovelace',
  inputType: 'text',
  inputLabel: 'Full name',
  placeholder: 'Type a name',
  validate: (value) => (value.trim() ? true : 'Name is required'),
});

alert and confirm get role="alertdialog" automatically. prompt accepts the extra options above on top of every DialogOptions field.

open()

The low-level API. It returns a DialogInstance immediately rather than a promise, so the dialog can be updated, moved, or closed from anywhere.

import { open } from 'forgedialog';

const dialog = open({
  title: 'Custom dialog',
  content: (container) => container.append(renderForm()),
  buttons: [
    { text: 'Cancel', onClick: (i) => i.close(null) },
    { text: 'Save', role: 'primary', autoFocus: true, onClick: (i) => i.close(read()) },
  ],
});

const result = await dialog.whenClosed();          // the result, or undefined
const { result: r, reason } = await dialog.whenSettled(); // result plus why it closed

Content and untrusted HTML

content accepts a string (rendered as text), an element, or a builder function. Markup needs an explicit decision:

// Untrusted markup: pass a sanitizer.
open({ html: userContent, sanitizeHtml: (h) => DOMPurify.sanitize(h) });

// Markup you already trust.
open({ unsafeHtml: '<p>Generated by us</p>' });

Close reasons

Every close carries a reason: 'button', 'escape', 'backdrop', 'api', 'abort', or 'destroy'. Read it with whenSettled().

DialogOptions

Accepted by open() and by every helper built on it.

ButtonConfig

DialogInstance

Appearance

Appearance overrides are scoped to one dialog and can be changed at runtime with update(). Opacity values are clamped to 0..1; plain numbers for widths, radii, and blur are read as pixels.

open({
  title: 'Styled',
  appearance: {
    opacity: 0.96,
    surfaceColor: '#12141a',
    overlayOpacity: 0.55,
    backdropBlur: 12,
    titleColor: '#ffd166',
    titleBackground: '#1b1740',
    contentColor: '#c8ccd4',
    borderColor: '#7c5cff',
    borderWidth: 2,
    radius: 20,
    shadow: { angle: 135, distance: 24, blur: 60, opacity: 0.45 },
  },
});

The full applier ships with forgedialog and forgedialog/core. On a focused entry, add import 'forgedialog/appearance' — without it the richer fields are ignored rather than throwing.

Shadows

shadow takes three shapes.

Corner radius

radius takes one value for every corner, any CSS border-radius string, or a per-corner object. Corners left out of that object keep the theme radius rather than collapsing to zero.

appearance: { radius: 20 }
appearance: { radius: '20px 20px 4px 4px' }
appearance: { radius: { topLeft: 24, topRight: 24, bottomRight: 4, bottomLeft: 4 } }

Drawers stay square and bottom sheets round only their top corners unless radius says otherwise.

Hover

hover restyles a dialog only while the pointer is over it, and only for dialogs that ask for it — every other dialog stays completely static. It reuses the colour, radius, and shadow fields and adds three of its own.

Hover transforms honour prefers-reduced-motion and are suspended while a dialog is being dragged, so they cannot push it outside its bounds.

Dragging

draggable: true is enough to move a dialog by its header. The object form adds constraints, keyboard support, and persistence. Dragging needs the interactions capability, which forgedialog enables for you.

Bottom sheets keep their own swipe-to-dismiss gesture and ignore general dragging.

Drawers, sheets, lightboxes, loading

import { drawer, bottomSheet, lightbox, loading } from 'forgedialog';

drawer({ title: 'Settings', side: 'right', content: renderSettings });

bottomSheet({ title: 'Share', content: renderShare });

lightbox('/photo.jpg', { alt: 'A photo', caption: 'Taken in 2026' });

const task = loading('Uploading…');
task.update('Almost there…');
await task.close();

These are open() with a presentation preset, so every DialogOptions field still applies.

Forms

form() builds a validated dialog from a field list and resolves with the values, or null if cancelled. Field names are inferred into the result type, so values.email is typed without a cast.

import { form } from 'forgedialog';

const values = await form(
  [
    { name: 'email', type: 'email', label: 'Email', required: true },
    { name: 'plan', type: 'select', label: 'Plan', options: [
      { value: 'free', label: 'Free' },
      { value: 'pro', label: 'Pro' },
    ] },
    { name: 'notes', type: 'textarea', label: 'Notes', rows: 4 },
  ],
  { title: 'Sign up', submitText: 'Create account' },
);

Field types: text, password, email, number, date, textarea, select, checkbox, radio, file. Each field takes label, defaultValue, placeholder, helpText, required, and a validate function; numbers add min, max, step, and files add accept, multiple, maxFiles, and maxSizeBytes.

formWizard(steps, options?) spreads the same fields over several steps, with nextText, backText, finishText, and an onStepChange callback.

Wizards

wizard() is the general form: each step renders whatever it likes, can validate, and can choose the next step from the data collected so far.

import { wizard } from 'forgedialog';

const flow = wizard({
  initialData: { email: '', plan: 'free' },
  persistKey: 'signup',      // resumes where the user left off
  confirmUnsaved: true,      // asks before discarding progress
  steps: [
    { id: 'account', title: 'Account', render: renderAccount, validate: validateAccount },
    { id: 'plan', title: 'Plan', render: renderPlan,
      next: (data) => (data.plan === 'pro' ? 'billing' : 'review') },
    { id: 'billing', title: 'Billing', render: renderBilling },
    { id: 'review', title: 'Review', render: renderReview },
  ],
});

const data = await flow.result; // the data, or null if cancelled

The controller also exposes next(), back(), goTo(stepId), getData(), and the underlying instance.

Toasts and notifications

import { toast, notificationCenter, getNotificationHistory } from 'forgedialog';

toast('Saved', { tone: 'success' });

// A duration of 0 or Infinity keeps it up until dismiss() is called.
const upload = toast('Uploading…', { duration: 0 });
upload.dismiss();

toast('Message sent', { action: { text: 'Undo', onClick: undoSend } });

notificationCenter();          // a dialog listing past toasts
getNotificationHistory();      // the same list as data

Tones are info, success, warning, and danger. clearNotificationHistory() empties the log.

Command palette

import { commandPalette } from 'forgedialog';

commandPalette([
  { id: 'new', label: 'New document', shortcut: '⌘N', run: createDocument },
  { id: 'search', label: 'Search', keywords: ['find', 'filter'], run: openSearch },
]);

Typing filters on the label and on keywords; the palette resolves with the id of the command that ran.

Theming

import { setTheme, getTheme, setThemePreset } from 'forgedialog';

setTheme('dark');    // 'light' | 'dark' | 'system'
getTheme();

setThemePreset('glass'); // 'default' | 'minimal' | 'glass' | 'material'

setTheme() writes data-fd-theme on <html>. Your own stylesheet can read the same attribute so the page and the dialogs switch together — that is exactly what this site does.

CSS custom properties

Everything visual is a variable on :root, so a theme can be written without touching JavaScript.

The per-dialog variables the appearance API writes (--fd-dialog-radius, --fd-dialog-shadow, --fd-dialog-title-background, and the rest) can also be set by hand if you would rather style in CSS than in JavaScript.

Labels and i18n

import { setLabels, getLabels } from 'forgedialog';

setLabels({
  ok: 'Đồng ý',
  cancel: 'Huỷ',
  close: 'Đóng',
  submit: 'Gửi',
  fieldRequired: 'Bắt buộc',
  promptPlaceholder: 'Nhập nội dung',
  notifications: 'Thông báo',
});

Labels set this way apply everywhere; a single dialog can override them with its own labels option.

Plugins and hooks

Five lifecycle hooks fire for every dialog: beforeOpen, afterOpen, beforeClose, afterClose, and beforeDestroy.

import { on, off, registerPlugin } from 'forgedialog';

// A single hook.
on('afterOpen', ({ instance, options }) => track('dialog', options.title));

// Or a plugin bundling several.
registerPlugin({
  name: 'analytics',
  install: (api) => api.on('afterClose', ({ reason }) => track('close', reason)),
  hooks: {
    beforeClose: ({ preventClose, result }) => {
      if (result === undefined) preventClose?.();
    },
  },
});

A hook receives { instance, options, result, reason, preventClose }. Calling preventClose() in beforeClose keeps the dialog open.

Framework adapters

Each adapter is a thin wrapper over open() that ties a dialog's lifetime to the component's, so nothing is left mounted after unmount.

// React and Vue share the same hook shape.
import { useForgeDialog } from 'forgedialog/react';
const { open } = useForgeDialog();
await open({ title: 'Hi' }).whenClosed();

// Svelte: an action on the triggering element.
import { dialogTrigger } from 'forgedialog/svelte';
// <button use:dialogTrigger={{ title: 'Hi' }}>Open</button>

// Web component.
import { defineForgeDialog } from 'forgedialog/web-component';
defineForgeDialog(); // <forge-dialog open title="Hi" message="…" size="md">

TypeScript, SSR, and CSP

• Types ship for both ESM and CJS. open<T>() threads its result type through buttons, whenClosed(), and the hooks.
• Importing the package on a server does not touch the DOM, so it is safe in SSR builds; the dialog is only created when you call the API in a browser.
• The bundle contains no eval and no new Function, which is enforced in CI, so it runs under a strict Content Security Policy. This site is served under one.
• Every entry point has an enforced gzip budget, checked on each pull request.