Dialog

Dialogs are modal overlays that require user interaction. They're used for critical information, confirmation, or complex tasks that require focus.

When to use

• To confirm destructive actions (delete, remove, etc.)
• To collect information through forms
• To display important information that requires acknowledgment
• For focused tasks that shouldn't be interrupted
• When you need to prevent interaction with the rest of the page

Key features

• Modal behavior - Blocks interaction with the rest of the page
• Multiple sizes - Small, medium, large, and full-screen options
• Focus management - Traps focus within the dialog
• Keyboard support - ESC to close, Tab to navigate
• Customizable content - Header, body, and footer sections
• Accessible - Full ARIA support and screen reader friendly

Anatomy

A dialog consists of the following structure:

Main Structure

• Container (.pm7-dialog) - Main wrapper with behavior attributes
• Overlay (.pm7-dialog-overlay) - Semi-transparent backdrop
• Content (.pm7-dialog-content) - The dialog box container

Content Markers (Input)

These attributes are used on the root pm7-dialog element or its direct children to define content and behavior:

• data-pm7-dialog="id" - Unique identifier for the dialog
• pm7-dialog-size - Dialog size: sm, md, lg, xl, full
• pm7-dialog-icon - Icon type: info, warning, error, success
• pm7-show-close - Shows the X close button in header
• pm7-header-separator - Add line separator under header
• pm7-no-escape - Prevents closing dialog with ESC key
• pm7-no-overlay-close - Prevents closing dialog when clicking backdrop
• pm7-header - Marks the header section. Content within this element becomes the header.
• pm7-dialog-title - Text for the main dialog title (used with pm7-header)
• pm7-dialog-subtitle - Text for the dialog subtitle/description (used with pm7-header)
• pm7-body - Marks the main content area
• pm7-footer - Marks the footer section for actions

Generated Elements (Output)

Based on the content markers, the following HTML elements and classes are generated:

• Header Container (.pm7-dialog-header)
• Header Text Container (.pm7-dialog-header-text) - Wraps title and description
• Icon (.pm7-dialog-icon) - SVG icon based on pm7-dialog-icon
• Title (.pm7-dialog-title) - H2 element for pm7-dialog-title
• Description (.pm7-dialog-description) - P element for pm7-dialog-subtitle
• Close Button (.pm7-dialog-close) - Button with X icon when pm7-show-close is set
• Header Separator (.pm7-dialog-header-separator) - Line when pm7-header-separator is set
• Body Container (.pm7-dialog-body)
• Footer Container (.pm7-dialog-footer)

Size Variants

• .pm7-dialog-content--sm - Small (400px max-width)
• .pm7-dialog-content--md - Medium (600px max-width, default)
• .pm7-dialog-content--lg - Large (800px max-width)
• .pm7-dialog-content--xl - Extra large (1000px max-width)
• .pm7-dialog-content--full - Full screen

Style Variants

• .pm7-dialog--alert - Error/warning style
• .pm7-dialog--success - Success style
• .pm7-dialog--loading - Loading state with spinner

Installation

npm install @pm7/core

CSS Classes

Data Attributes

PM7 Dialog supports two approaches: Traditional HTML structure and the new Content Marker system that automatically generates dialog structure.

Root Dialog Attributes

Content Marker Attributes (for sections)

Legacy Content Marker Attributes

Note: These attributes (without data- prefix) are deprecated but still supported for backward compatibility.

Basic Usage

<!-- Content Marker System (Recommended) -->
<div class="pm7-dialog" 
     data-pm7-dialog="my-dialog" 
     data-pm7-dialog-size="md" 
     data-pm7-show-close>
  <div data-pm7-header
       data-pm7-dialog-title="Dialog Title"
       data-pm7-dialog-subtitle="Optional subtitle text"
       data-pm7-header-separator>
  </div>
  
  <div data-pm7-body>
    <p>Your dialog content goes here.</p>
  </div>
  
  <div data-pm7-footer>
    <button class="pm7-button pm7-button--outline" onclick="closeDialog('my-dialog')">
      Cancel
    </button>
    <button class="pm7-button pm7-button--primary">
      Confirm
    </button>
  </div>
</div>

<!-- Dialog with Icon -->
<div class="pm7-dialog" 
     data-pm7-dialog="info-dialog" 
     data-pm7-dialog-size="sm">
  <div data-pm7-header
       data-pm7-dialog-title="Information"
       data-pm7-dialog-icon="info"
       data-pm7-header-separator>
  </div>
  <div data-pm7-body>
    <p>This is an informational message.</p>
  </div>
  <div data-pm7-footer>
    <button class="pm7-button pm7-button--primary" onclick="closeDialog('info-dialog')">
      Got it
    </button>
  </div>
</div>

<!-- Traditional HTML Structure -->
<div class="pm7-dialog" data-pm7-dialog="traditional-dialog">
  <div class="pm7-dialog-overlay"></div>
  <div class="pm7-dialog-content pm7-dialog-content--md">
    <div class="pm7-dialog-header">
      <h2 class="pm7-dialog-title">Dialog Title</h2>
      <button class="pm7-dialog-close" aria-label="Close">
        <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
          <line x1="18" y1="6" x2="6" y2="18"/>
          <line x1="6" y1="6" x2="18" y2="18"/>
        </svg>
      </button>
    </div>
    <div class="pm7-dialog-body">
      <p>Dialog content goes here.</p>
    </div>
    <div class="pm7-dialog-footer">
      <button class="pm7-button pm7-button--outline" onclick="closeDialog('traditional-dialog')">
        Cancel
      </button>
      <button class="pm7-button pm7-button--primary">
        Confirm
      </button>
    </div>
  </div>
</div>

<!-- Trigger Button -->
<button class="pm7-button" onclick="openDialog('my-dialog')">
  Open Dialog
</button>

JavaScript API

The following functions are globally available for convenience, but can also be imported from @pm7/core:

• openDialog(id): Opens a dialog by its `pm7-dialog` ID.
• closeDialog(id): Closes a dialog by its `pm7-dialog` ID.
• pm7Alert(message, options): Shows a simple alert dialog.
• pm7Confirm(message, callback, options): Shows a confirmation dialog.

import { PM7Dialog, createDialog, pm7Alert, pm7Confirm } from '@pm7/core';

// Initialize a dialog (for traditional structure)
const dialogElement = document.querySelector('[data-pm7-dialog="my-dialog"]');
const dialog = new PM7Dialog(dialogElement);

// Open/close programmatically
dialog.open();
dialog.close();

// Add shake animation
dialog.shake();

// Set loading state
dialog.setLoading(true);

// Listen for events
dialogElement.addEventListener('pm7-dialog-open', () => {
  console.log('Dialog opened');
});

dialogElement.addEventListener('pm7-dialog-close', () => {
  console.log('Dialog closed');
});

// Global functions (auto-loaded)
openDialog('my-dialog');
closeDialog('my-dialog');

// Programmatic dialog creation
const dialog = createDialog({
  id: 'dynamic-dialog',
  title: 'Dynamic Dialog',
  subtitle: 'Created programmatically',
  body: '<p>This dialog was created with JavaScript.</p>',
  footer: `
    <button class="pm7-button pm7-button--primary" onclick="closeDialog('dynamic-dialog')">
      Close
    </button>
  `,
  size: 'md',
  showClose: true,
  icon: 'info'
});

// Utility functions
pm7Alert('This is an alert message');
pm7Confirm('Are you sure?', (confirmed) => {
  if (confirmed) {
    console.log('User confirmed');
  }
});

CSS Customization

Dialogs support dark mode and can be customized with CSS variables:

:root {
  --pm7-dialog-bg: white;
  --pm7-dialog-overlay-bg: rgb(0 0 0 / 0.5);
}

[data-theme="dark"] {
  --pm7-dialog-bg: #1a1a1a;
  --pm7-dialog-overlay-bg: rgb(0 0 0 / 0.8);
}

React Usage

Note: The React wrapper will need to be updated to support the new structure. The vanilla JavaScript version uses the new content markers as shown above.

// Future React API (to be implemented)
import { Dialog } from '@pm7/react';

function MyComponent() {
  return (
    <div className="pm7-dialog" data-pm7-dialog="react-dialog">
      <div data-pm7-header data-pm7-dialog-title="Edit Profile"></div>
      <div data-pm7-body>
        <p>Dialog content goes here</p>
      </div>
      <div data-pm7-footer>
        <button className="pm7-button pm7-button--outline">
          Cancel
        </button>
        <button className="pm7-button pm7-button--primary">
          Save Changes
        </button>
      </div>
    </div>
  );
}

Accessibility

• Focus trap: Focus stays within dialog while open
• Escape key: Closes the dialog (unless pm7-no-escape is set)
• Click outside: Closes dialog by clicking overlay (unless pm7-no-overlay-close is set)
• Focus restoration: Focus returns to trigger element on close
• ARIA attributes: Proper roles and labels for screen readers
• Heading hierarchy: Semantic heading structure
• Keyboard navigation: Tab through interactive elements

Copy this link that can be used as documentation for working with this component: