BackdropManager

Overview

BackdropManager is the backdrop overlay management system in Now.js Framework. It supports multiple backdrops, animations, and keyboard handling.

When to use:

• Need backdrop for modals, dialogs
• Need overlay with click handler
• Need stacking multiple overlays
• Need prevent body scroll

Why use it:

• ✅ Automatic z-index management
• ✅ Multiple backdrop stacking
• ✅ Click handlers
• ✅ Keyboard support (Escape)
• ✅ Smooth animations
• ✅ Scroll prevention

Basic Usage

Show Backdrop

// Simple backdrop
const backdropId = BackdropManager.show(targetElement);

// With click handler
const backdropId = BackdropManager.show(element, () => {
  console.log('Backdrop clicked');
  closeModal();
});

// With options
const backdropId = BackdropManager.show(element, onClickHandler, {
  background: 'rgba(0, 0, 0, 0.7)',
  opacity: 0.7,
  className: 'custom-backdrop'
});

Hide Backdrop

// Hide specific backdrop
BackdropManager.hide(backdropId);

// Hide all backdrops
BackdropManager.hideAll();

Configuration

await BackdropManager.init({
  // Base z-index for first backdrop
  baseZIndex: 990,

  // Animation settings
  animation: true,
  duration: 200,        // Animation duration (ms)
  useTransition: true,

  // Appearance
  className: 'backdrop',
  background: 'rgba(0,0,0,0.5)',
  opacity: 0.5,

  // Behavior
  preventScroll: true,  // Prevent body scroll when active
  debug: false
});

API Reference

BackdropManager.init(options)

Initialize BackdropManager

Returns: Promise<BackdropManager>

BackdropManager.show(element, onClick?, options?)

Show backdrop

Returns: number - Backdrop ID

const id = BackdropManager.show(modalElement, () => {
  BackdropManager.hide(id);
});

BackdropManager.hide(id)

Hide backdrop

BackdropManager.hideAll()

Hide all backdrops

BackdropManager.update(element, options)

Update backdrop options

BackdropManager.isActive(element)

Check if backdrop is active

Returns: boolean

BackdropManager.getBackdropById(id)

Get backdrop element

Returns: HTMLElement|null

BackdropManager.destroy()

Destroy manager and cleanup

Keyboard Handling

Press Escape to close topmost backdrop:

// Automatically handled
// Press Escape to hide topmost backdrop

CSS Styling

/* Base backdrop style */
.backdrop {
  position: fixed;
  top: 0;
  left: 0;
  width: 100vw;
  height: 100vh;
  background: rgba(0, 0, 0, 0.5);
  z-index: 990;
}

/* Custom backdrop */
.backdrop.dark {
  background: rgba(0, 0, 0, 0.8);
}

.backdrop.blur {
  backdrop-filter: blur(4px);
}

.backdrop.light {
  background: rgba(255, 255, 255, 0.9);
}

Real-World Examples

Modal with Backdrop

function openModal(modalElement) {
  const backdropId = BackdropManager.show(modalElement, () => {
    closeModal(modalElement, backdropId);
  });

  modalElement.classList.add('open');
  modalElement.dataset.backdropId = backdropId;
}

function closeModal(modalElement, backdropId) {
  modalElement.classList.remove('open');
  BackdropManager.hide(backdropId || modalElement.dataset.backdropId);
}

Multiple Stacked Modals

// First modal
const backdrop1 = BackdropManager.show(modal1, () => closeModal1());
modal1.style.zIndex = 1001;

// Second modal (stacks on top)
const backdrop2 = BackdropManager.show(modal2, () => closeModal2());
modal2.style.zIndex = 1011;

// Escape closes topmost first
// Z-index automatically managed (990, 1000, 1010, ...)

Sidebar with Backdrop

function openSidebar() {
  const sidebar = document.getElementById('sidebar');
  sidebar.classList.add('open');

  const backdropId = BackdropManager.show(sidebar, () => {
    closeSidebar();
  }, {
    background: 'rgba(0, 0, 0, 0.3)'
  });

  sidebar.dataset.backdropId = backdropId;
}

function closeSidebar() {
  const sidebar = document.getElementById('sidebar');
  sidebar.classList.remove('open');
  BackdropManager.hide(sidebar.dataset.backdropId);
}

Integration with DialogManager

DialogManager uses BackdropManager automatically:

// DialogManager.show() calls BackdropManager.show() internally
const dialog = DialogManager.custom({
  title: 'Modal Title',
  message: 'Content'
});

// Backdrop created and managed automatically

Common Pitfalls

⚠️ 1. Store Backdrop ID

// ❌ Not storing ID - can't hide later
BackdropManager.show(element);

// ✅ Store ID for hiding
const backdropId = BackdropManager.show(element);
// Use backdropId in hide()

⚠️ 2. Z-index of Content

// Backdrop z-index: 990, 1000, 1010, ...
// Content must have higher z-index than backdrop

const backdropId = BackdropManager.show(modal);
modal.style.zIndex = 1001; // Higher than backdrop (1000)

⚠️ 3. Cleanup When Removing Element

// ❌ Removing element without hiding backdrop
element.remove();

// ✅ Hide backdrop first
BackdropManager.hide(backdropId);
element.remove();

Related Documentation

• DialogManager - Dialog boxes
• Modal - Modal windows