Overlays Foundation

The Overlays Foundation provides core services for building overlay components like Dialogs, Snackbars, and custom components. This page demonstrates the foundation services with interactive examples.

For App Developers: See the Dialogs page for foundation services in context of real components.

For Component Developers: This page shows how to use foundation services directly when building custom overlay components.

1. Stack Manager Visualizer

The OverlayStackManager tracks all open overlays and assigns z-index values. Use this visualizer to see how overlays stack in real-time.

Current Overlay Stack

No overlays currently open. Use the buttons below to spawn test overlays.

Statistics

Total Open: 0

Modal Overlays: 0

Top Z-Index: N/A

csharp

@inject IOverlayStackManager StackManager

// Register an overlay
var registration = new OverlayRegistration(
    id: Guid.NewGuid(),
    type: OverlayType.Dialog,
    isModal: true
);
var zIndex = StackManager.Register(registration);

// Unregister when done
StackManager.Unregister(registration.Id);

2. Focus Trap Sandbox

The FocusTrapService keeps keyboard navigation within a container. Try tabbing through the sandbox to see focus cycling in action.

Focus Trap Container

When focus trap is enabled, Tab/Shift+Tab will cycle through the elements below and cannot escape this container.

Focusable Link

csharp

@inject IFocusTrapService FocusTrapService

// Activate focus trap
await FocusTrapService.ActivateAsync(
    containerId: "my-dialog-container",
    options: new FocusTrapOptions
    {
        AutoFocus = true,
        InitialFocusSelector = "button",
        ReturnFocusOnDeactivate = true,
        FocusDelayMs = 0
    }
);

// Deactivate focus trap
await FocusTrapService.DeactivateAsync("my-dialog-container");

3. Scroll Lock Tester

The ScrollLockService prevents background scrolling when modals are open. Test scroll locking with reference counting for multiple locks.

Scroll this page, then enable scroll lock to prevent background scrolling. Add multiple locks to test reference counting.

Current Lock Status

Service Lock Count

Is Locked

Locks Added (This Demo)

No scroll locks active. Background scrolling is enabled.

How It Works

Reference Counting: Multiple overlays can lock scroll independently
iOS Compatible: Uses position:fixed to prevent scroll-jank on mobile
Position Preservation: Your scroll position is saved and restored
Automatic Unlock: Scroll unlocks when all locks are removed

csharp

@inject IScrollLockService ScrollLockService

// Lock scrolling (increments internal reference count)
await ScrollLockService.LockAsync();

// Unlock scrolling (decrements internal reference count)
await ScrollLockService.UnlockAsync();

// Check lock status
bool isLocked = ScrollLockService.IsLocked;  // True if any locks active
int lockCount = ScrollLockService.LockCount; // Current reference count

// Multiple overlays can lock independently:
await ScrollLockService.LockAsync();    // Lock count: 1, IsLocked: true
await ScrollLockService.LockAsync();    // Lock count: 2, IsLocked: true
await ScrollLockService.UnlockAsync();  // Lock count: 1, IsLocked: true
await ScrollLockService.UnlockAsync();  // Lock count: 0, IsLocked: false

4. Dismissal Policy Tester

The DismissalCoordinator handles ESC key and backdrop/outside click dismissal. Test the three policy presets to understand their behavior.

Critical Policy

Requires explicit user action. No ESC, no backdrop click.

Configuration:

CloseOnEscape: false
CloseOnBackdrop: false
CloseOnOutside: false

Try: Press ESC → Blocked
Try: Click outside → Ignored

Use for: Destructive actions, required confirmations, critical warnings

Standard Policy

Default for most dialogs. ESC + backdrop click enabled.

Configuration:

CloseOnEscape: true
CloseOnBackdrop: true
CloseOnOutside: false

Try: Press ESC → Closes
Try: Click backdrop → Closes

Use for: General dialogs, forms, modals, most UI overlays

Positioned Policy

For popovers/tooltips. ESC + outside click, no backdrop.

Configuration:

CloseOnEscape: true
CloseOnBackdrop: false
CloseOnOutside: true

Try: Press ESC → Closes
Try: Click outside → Closes

Use for: Popovers, tooltips, dropdown menus, context menus

csharp

@inject IDismissalCoordinator DismissalCoordinator

// Subscribe to dismissal events
var policy = DismissalPolicy.Standard; // or Critical, Positioned
var subscription = DismissalCoordinator.Subscribe(
    overlayId: "my-dialog",
    policy: policy,
    onDismiss: (overlayId, reason) =>
    {
        Console.WriteLine($"Dismissed: {overlayId}, Reason: {reason}");
        // Close your overlay here
    }
);

// Unsubscribe when done
DismissalCoordinator.Unsubscribe("my-dialog");

// Policy presets:
var critical = DismissalPolicy.Critical;    // No ESC, no backdrop
var standard = DismissalPolicy.Standard;    // ESC + backdrop
var positioned = DismissalPolicy.Positioned; // ESC + outside click

Service Reference

Core services provided by the Overlays Foundation.

Core Services

No properties defined.

Z-Index Hierarchy

Snackbars: Base 1100 (highest priority notifications)
Dialogs/Drawers: Base 1000 (modal blocking layer)
Popovers/Tooltips/ContextMenus: Base 999 (contextual helpers)