Skip to content

Pending Review

Pending Review from User Experience (UX)

Dialog Component

Overview

The PWC Dialog is a modal overlay component in the Progress Web Components design system. It provides accessible, responsive modal dialogs with built-in backdrop management, size variants, and flexible content layout across React and Angular applications.

Core Capabilities

  • Modal Overlay Management - Built-in backdrop and focus management for accessible modal interactions
  • Multiple Size Variants - Three size options (small, medium, large) to accommodate different content requirements
  • Flexible Content Layout - Column-based layout with optional heading, hint text, and slotted content areas
  • Automatic Focus Management - Proper focus trapping and restoration for keyboard accessibility
  • Close Button Integration - Built-in close functionality with customizable event handling
  • Responsive Design - Adaptive sizing with maximum height constraints and viewport-aware dimensions

When to use Dialog:

  • Display important information or confirmations that require user attention before proceeding
  • Create forms or input interfaces that need to be presented separately from the main content
  • Show detailed information, settings panels, or complex interactions in an overlay context
  • Implement confirmation dialogs for destructive actions or critical user decisions

When not to use Dialog:

  • Simple tooltips or contextual help that doesn't require modal interaction
  • Navigation menus or dropdowns that should remain part of the page flow
  • Content that users need to reference while interacting with the main interface

Basic Implementation

import React, { useState } from 'react';
import { PwcDialog, PwcButton } from "@progress-i360/pwc-react";

function ConfirmDialog() {
  const [isOpen, setIsOpen] = useState(false);

  return (
      <>
        <PwcButton 
          label="Delete Account" 
          variant="primary"
          onClick={() => setIsOpen(true)} 
        />

        <PwcDialog
          open={isOpen}
          heading="Confirm Deletion"
          size="s"
          onClose={() => setIsOpen(false)}
        >
          <div style={{ padding: '20px' }}>
            <p>Are you sure you want to delete your account?</p>
            <div style={{ display: 'flex', gap: '12px', justifyContent: 'flex-end', marginTop: '24px' }}>
              <PwcButton variant="outline" label="Cancel" onClick={() => setIsOpen(false)} />
              <PwcButton variant="primary" label="Delete" onClick={() => setIsOpen(false)} />
            </div>
          </div>
        </PwcDialog>
      </>
  );
}

import { useState } from 'react';
import '@progress-i360/progress-web-components/dialog';
import '@progress-i360/progress-web-components/button';
import '@progress-i360/progress-web-components/input';

function SettingsDialog() {
  const [isOpen, setIsOpen] = useState(false);
  const [username, setUsername] = useState('john.doe');

  return (
      <>
        <pwc-button 
          label="Settings" 
          onPwcClick={() => setIsOpen(true)}
        ></pwc-button>

        <pwc-dialog
          open={isOpen}
          heading="User Settings"
          size="m"
          onPwcClose={() => setIsOpen(false)}
        >
          <div style={{ padding: '24px' }}>
            <pwc-input
              label="Username"
              value={username}
              onInput={(event) => setUsername((event.target as HTMLInputElement).value)}
            ></pwc-input>
            <div style={{ display: 'flex', gap: '12px', justifyContent: 'flex-end', marginTop: '24px' }}>
              <pwc-button variant="outline" label="Cancel" onPwcClick={() => setIsOpen(false)}></pwc-button>
              <pwc-button variant="primary" label="Save" onPwcClick={() => setIsOpen(false)}></pwc-button>
            </div>
          </div>
        </pwc-dialog>
      </>
  );
}

import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
import '@progress-i360/progress-web-components/dialog';
import '@progress-i360/progress-web-components/button';

@Component({
  selector: 'dialog-demo',
  template: `
    <pwc-dialog
      [open]="showDialog"
      [heading]="dialogTitle"
      hint="This is a simple dialog example"
      (pwc-close)="showDialog = false">
      <p>{{dialogMessage}}</p>
      <pwc-button label="Update Message" (pwc-click)="updateMessage()"></pwc-button>
    </pwc-dialog>
    <pwc-button label="Open Dialog" (pwc-click)="openDialog()"></pwc-button>
  `,
  schemas: [CUSTOM_ELEMENTS_SCHEMA]
})
export class DialogDemo {
  showDialog = false;
  dialogTitle = 'Welcome';
  dialogMessage = 'This is a sample dialog with dynamic content.';

  openDialog() {
    this.showDialog = true;
  }

  updateMessage() {
    const messages = [
      'Message updated successfully!',
      'Here is some new information.',
      'Dialog content can be changed dynamically.',
      'This demonstrates interactive functionality.'
    ];
    this.dialogMessage = messages[Math.floor(Math.random() * messages.length)];
    this.dialogTitle = 'Updated';
  }
}

// Create confirmation dialog
const dialog = document.createElement('pwc-dialog');
dialog.setAttribute('heading', 'Confirm Action');
dialog.setAttribute('hint', 'This action cannot be undone');
dialog.setAttribute('size', 's');

// Add dialog content
const content = document.createElement('div');
content.style.padding = '20px';
content.textContent = 'Are you sure you want to continue?';
dialog.appendChild(content);

// Handle dialog close event
dialog.addEventListener('close', () => {
  console.log('Dialog was closed');
});

// Show dialog by setting open property
dialog.open = true;

// Add to page
document.body.appendChild(dialog);

Usage Patterns

  • Confirmation Dialogs - Present critical decisions or destructive actions with clear confirm/cancel options
  • Form Overlays - Display complex forms or data entry interfaces that require focused user attention
  • Information Display - Show detailed information, help content, or system status that doesn't fit in the main interface
  • Settings and Preferences - Provide configuration interfaces that can be accessed from multiple locations in the application

Best Practices

Content Strategy Guidelines

  • Clear Purpose - Use descriptive headings and hint text to immediately communicate the dialog's purpose and required actions
  • Concise Content - Keep dialog content focused and avoid overwhelming users with too much information at once
  • Action Hierarchy - Place primary actions (like "Save" or "Confirm") on the right and secondary actions (like "Cancel") on the left
  • Progressive Disclosure - Use appropriate dialog sizes and consider breaking complex content into multiple steps or tabs

Performance Optimization

  • Lazy Loading - Load dialog content only when needed to improve initial page load performance
  • Memory Management - Properly clean up event listeners and component state when dialogs are closed
  • Focus Management - Leverage the built-in focus trapping and restoration to maintain accessibility without custom implementations
  • Backdrop Optimization - Use the native dialog backdrop rather than custom overlay implementations for better performance

Integration Architecture

  • State Management - Integrate dialog state with your application's state management system for consistent behavior
  • Event Handling - Implement proper event delegation and use the built-in close event for consistent dialog management
  • Form Integration - Coordinate dialog forms with validation systems and ensure proper error handling
  • Accessibility Support - Maintain proper ARIA attributes and ensure keyboard navigation works seamlessly with screen readers

Common Use Cases

Confirmation and Alert Dialogs

  • Display destructive action confirmations with clear visual hierarchy and appropriate button styling
  • Show system alerts or notifications that require user acknowledgment before proceeding
  • Present warning messages with context-specific information and appropriate action choices

Data Entry and Form Dialogs

  • Create user profile editing interfaces with form validation and save/cancel functionality
  • Build data creation wizards that guide users through multi-step processes
  • Design settings panels that allow configuration changes without leaving the current page context

Information and Detail Views

  • Display comprehensive data views like analytics dashboards or detailed record information
  • Show help content, documentation, or tutorial information in an accessible overlay format
  • Present media viewers, image galleries, or document previews with appropriate sizing and controls

Troubleshooting

Common Issues

Dialog Not Opening or Closing

Problem: Dialog doesn't respond to open/close state changes or appears to be stuck.

Solution:

  • Verify that the open property is being set correctly and that the component is properly updated. Check for JavaScript errors that might prevent the dialog element's showModal() or close() methods from executing.

Focus Management Problems

Problem: Focus doesn't return to the triggering element after dialog closes or gets trapped incorrectly.

Solution:

  • Ensure you're using the native HTML dialog element's built-in focus management. Avoid custom focus handling that might conflict with the browser's native behavior. Check that the dialog is properly closed rather than just hidden.

Backdrop Click Not Working

Problem: Clicking outside the dialog doesn't close it or behaves inconsistently.

Solution:

  • The component uses the native dialog backdrop behavior. If you need custom backdrop click handling, listen for click events on the dialog element itself and check if the click target is the dialog (not its contents).

Size and Layout Issues

Problem: Dialog content overflows or doesn't display properly within the size constraints.

Solution:

  • Review the content size and choose the appropriate dialog size (s, m, l). For very large content, consider using the large size variant or implementing scrollable content areas within the dialog body.

Implementation Support

  • Storybook Examples - Interactive examples showing all dialog sizes, configurations, and common usage patterns
  • Accessibility Guidelines - Complete WCAG compliance support with proper focus management and screen reader compatibility
  • Design System Integration - Consistent styling and behavior that aligns with PWC design tokens and component patterns

Resources

Storybook Documentation

For comprehensive API documentation, interactive examples, and testing tools: 📖 View Complete API Documentation in Storybook →

For additional implementation guidance or framework-specific questions, consult the PWC Design System documentation or reach out to the component library team.