syncfusion-javascript-popups

# Syncfusion EJ2 JavaScript Popups ## Overview The Syncfusion EJ2 JavaScript Popups library provides three essential UI components for building interactive overlay content. Each component is fully documented with TypeScript/JavaScript examples, accessibility guidelines, and common usage patterns. All components support: - **Accessibility:** WCAG 2.2 Level AA, Section 508, ADA compliance - **Themes:** Material 3, Bootstrap 5, Fluent, Tailwind 3, Fabric - **APIs:** Imperative TypeScript/JavaScript with full event support - **Keyboard:** Full keyboard navigation and interaction --- ## Component Overview ### Quick Navigation | Component | Purpose | Package | Files | |-----------|---------|---------|-------| | **Dialog** | Modal/modeless dialog with templates | ej2-popups | 8 | | **Predefined Dialog** | Alert/Confirm/Prompt via DialogUtility | ej2-popups | 7 | | **Tooltip** | Contextual popup on hover/focus/click | ej2-popups | 9 | **Package:** `@syncfusion/ej2-popups` --- ## Dialog Component **Purpose:** Displays content in an overlay window above the main page, supporting modal/modeless modes, custom templates, action buttons, animations, drag, resize, and built-in utility dialogs (alert/confirm). **Package:** `@syncfusion/ej2-popups` ### Quick Example ```typescript import { Dialog } from '@syncfusion/ej2-popups'; import { enableRipple } from '@syncfusion/ej2-base'; enableRipple(true); let dialog: Dialog = new Dialog({ header: 'Welcome', content: 'This is a simple dialog.', showCloseIcon: true, width: '350px', target: document.body, buttons: [ { buttonModel: { content: 'OK', isPrimary: true }, click: () => { dialog.hide(); } } ] }); dialog.appendTo('#dialog'); ``` ### Documentation - [dialog-getting-started.md](./references/dialog-getting-started.md) - Setup and installation - [dialog-templates.md](./references/dialog-templates.md) - Header, content, and footer templates - [dialog-features.md](./references/dialog-features.md) - Animation, resize, localization, RTL - [dialog-events.md](./references/dialog-events.md) - All dialog events - [dialog-how-to.md](./references/dialog-how-to.md) - Common how-to scenarios - [dialog-dialog-utility.md](./references/dialog-dialog-utility.md) - DialogUtility.alert() and confirm() - [dialog-accessibility.md](./references/dialog-accessibility.md) - WCAG 2.2, ARIA, keyboard - [dialog-api.md](./references/dialog-api.md) - Complete API reference --- ## Predefined Dialog Component **Purpose:** Imperative alert, confirm, and prompt dialogs opened via the `DialogUtility` class. No component instance required—perfect for simple notifications and user confirmations. **Package:** `@syncfusion/ej2-popups` ### Quick Example - Alert ```typescript import { DialogUtility } from '@syncfusion/ej2-popups'; let dialogObj: any = DialogUtility.alert({ title: 'Low Battery', content: '10% of battery remaining', width: '250px', okButton: { click: () => dialogObj.hide() } }); ``` ### Quick Example - Confirm ```typescript import { DialogUtility } from '@syncfusion/ej2-popups'; let dialogObj: any = DialogUtility.confirm({ title: 'Delete File', content: 'Are you sure you want to delete this file?', okButton: { text: 'Delete', click: () => { /* delete logic */ dialogObj.hide(); } }, cancelButton: { text: 'Cancel', click: () => dialogObj.hide() } }); ``` ### Quick Example - Prompt ```typescript import { DialogUtility } from '@syncfusion/ej2-popups'; let dialogObj: any = DialogUtility.confirm({ title: 'Enter Name', content: '<input id="nameInput" class="e-input" placeholder="Your name" />', okButton: { text: 'Submit', click: () => { const name: string = (document.getElementById('nameInput') as HTMLInputElement).value; console.log('Name:', name); dialogObj.hide(); } } }); ``` ### Documentation - [predefineddialog-getting-started.md](./references/predefineddialog-getting-started.md) - Alert, Confirm, Prompt basics - [predefineddialog-animation.md](./references/predefineddialog-animation.md) - Animation effects - [predefineddialog-position.md](./references/predefineddialog-position.md) - 9 positions and custom coordinates - [predefineddialog-dimension.md](./references/predefineddialog-dimension.md) - Width, height, CSS constraints - [predefineddialog-draggable.md](./references/predefineddialog-draggable.md) - Draggable dialogs - [predefineddialog-customization.md](./references/predefineddialog-customization.md) - Button customization, close icon, content - [predefineddialog-api.md](./references/predefineddialog-api.md) - Complete API reference --- ## Tooltip Component **Purpose:** Displays contextual popup information when users hover, focus, or click on target elements. Supports 12 positions, multiple open modes, animations, custom content, and full accessibility. **Package:** `@syncfusion/ej2-popups` ### Quick Example ```typescript import { Tooltip } from '@syncfusion/ej2-popups'; let tooltip: Tooltip = new Tooltip({ content: 'Tooltip Content', position: 'TopCenter' }); tooltip.appendTo('#target'); ``` ### Quick Example - Multiple Targets ```typescript import { Tooltip } from '@syncfusion/ej2-popups'; let tooltip: Tooltip = new Tooltip({ target: '.e-info', position: 'RightCenter' }); tooltip.appendTo('#container'); ``` **HTML:** ```html <div id="container"> <input type="text" class="e-info" title="Please enter your name" /> <input type="email" class="e-info" title="Enter a valid email address" /> </div> ``` ### Documentation - [tooltip-getting-started.md](./references/tooltip-getting-started.md) - Setup and basic usage - [tooltip-content.md](./references/tooltip-content.md) - Content strategies, templates, dynamic loading - [tooltip-position.md](./references/tooltip-position.md) - 12 positions, tip pointer, offsets - [tooltip-open-mode.md](./references/tooltip-open-mode.md) - Hover, Click, Focus, Custom, Sticky - [tooltip-animation.md](./references/tooltip-animation.md) - Animation effects - [tooltip-customization.md](./references/tooltip-customization.md) - CSS customization, themes - [tooltip-how-to.md](./references/tooltip-how-to.md) - Common patterns and solutions - [tooltip-accessibility.md](./references/tooltip-accessibility.md) - WCAG 2.2, ARIA, keyboard - [tooltip-api.md](./references/tooltip-api.md) - Complete API reference --- ## Installation and Setup ### Install the Package ```bash npm install @syncfusion/ej2-popups@33.x.x --save npm audit ``` ### Add CSS Theme Imports ```css /* src/styles.css */ @import '../node_modules/@syncfusion/ej2-base/styles/tailwind3.css'; @import '../node_modules/@syncfusion/ej2-buttons/styles/tailwind3.css'; @import '../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css'; ``` Other available themes: `material.css`, `bootstrap5.css`, `fluent.css`, `fabric.css` --- ## Common Patterns ### Modal Dialog with Confirmation ```typescript import { Dialog } from '@syncfusion/ej2-popups'; let dialog: Dialog = new Dialog({ header: 'Confirm Action', content: 'Are you sure you want to proceed?', isModal: true, showCloseIcon: true, width: '400px', target: document.body, buttons: [ { buttonModel: { content: 'Yes', isPrimary: true }, click: () => { /* action */ dialog.hide(); } }, { buttonModel: { content: 'No', cssClass: 'e-flat' }, click: () => dialog.hide() } ] }); dialog.appendTo('#dialog'); ``` ### Quick Alert Notification ```typescript import { DialogUtility } from '@syncfusion/ej2-popups'; DialogUtility.alert('Operation completed successfully!'); ``` ### Form Validation Tooltip ```typescript import { Tooltip } from '@syncfusion/ej2-popups'; let emailTooltip: Tooltip = new Tooltip({ content: 'Please enter a valid email address', position: 'RightCenter', opensOn: 'Focus' }); emailTooltip.appendTo('#email'); ``` ### Draggable Dialog ```typescript import { DialogUtility } from '@syncfusion/ej2-popups'; let dialogObj: any = DialogUtility.alert({ title: 'Draggable', content: 'Drag me by the header', isDraggable: true, okButton: { click: () => dialogObj.hide() } }); ``` ### Tooltip on Disabled Elements ```typescript import { Tooltip } from '@syncfusion/ej2-popups'; let tooltip: Tooltip = new Tooltip({ content: 'This feature is currently disabled', position: 'TopCenter' }); tooltip.appendTo('#disabled-wrapper'); ``` **HTML:** ```html <span id="disabled-wrapper" style="display: inline-block;"> <button class="e-btn" disabled>Disabled</button> </span> ``` --- ## Theme Support All popup components support the following themes: | Theme | CSS File | |-------|----------| | Material 3 | `material.css` | | Bootstrap 5 | `bootstrap5.css` | | Fluent | `fluent.css` | | Tailwind 3 | `tailwind3.css` | | Fabric | `fabric.css` | --- ## Accessibility All popup components comply with WCAG 2.2 Level AA, Section 508, and ADA standards. ### Dialog Accessibility - WAI-ARIA roles and attributes - Keyboard navigation (Tab, Enter, Escape) - Focus management - Screen reader support ### Predefined Dialog Accessibility - Inherits Dialog accessibility features - Alert, Confirm, and Prompt patterns follow ARIA best practices - Keyboard navigation for all buttons ### Tooltip Accessibility - `role="tooltip"` with `aria-describedby` - `aria-hidden` for visibility state - Keyboard support (Escape to close, Focus to open) - Screen reader announcements - `prefers-reduced-motion` respect --- ## Browser Support - Chrome (latest) - Firefox (latest) - Safari (latest) - Edge (latest) - Internet Explorer 11 (with polyfills) --- ## Version Compatibility | Syncfusion EJ2 Version | Status | |------------------------|--------| | 33.x.x | Current (Recommended) | | 32.x.x | Supported | | 31.x.x | Supported | | < 30.x.x | Legacy | --- ## Quick Reference | Need | Component | Method/Property |