P11 Blazor UI Library – Bootstrap 5.3 Components

P11OverlayNative Component

The P11OverlayNative is a lightweight, high-performance media and content viewer. While P11ModalNative is for complex forms and dialogs, the Overlay is optimized for media previews, image galleries, and quick info. It uses a sibling-DOM approach to bypass stacking context issues on mobile devices while maintaining a black-out, high-contrast native look.

Seamless Integration & Background Control

This component provides a distraction-free experience by managing the underlying page state automatically:

Focus & Scroll Lock: When opened, it locks the background scrolling and traps the keyboard focus to the close actions, ensuring accessibility (ARIA).
Adaptive Navigation: The header layout changes dynamically: iOS shows a 'Back' text, Android a left arrow, macOS the traffic-light buttons, and Windows a classic top-right close button.
Lightweight Stack: It registers itself for the Escape key and Hardware Back-Button support, making it feel like a truly native system overlay.

Media Optimized

Specifically designed to handle large images and media. Includes auto-scaling to ensure content stays within the viewport on all devices.

True Black-Out

Uses a deep-black backdrop to put your content in focus, matching the native full-screen preview behavior of iOS Photos or Android Gallery.

Pro Tip: Use CssClassContent='p-0' to display edge-to-edge images. The component will automatically ensure that the Close-Buttons remain visible and accessible on top of your content.

Overlay native example

This section demonstrates the usage of the P11OverlayNative component with various configurations and highlights its key features.

Select platform simulation

Current mode: WEB

Implementation Details

<h2 class="mb-3">@AppState!.T("Overlay native example")</h2>
<p>
    @((MarkupString)@AppState!.T("This section demonstrates the usage of the <code>P11OverlayNative</code> component with various configurations and highlights its key features."))
</p>

<div class="container mt-5">
    <div class="mb-4 p-3 border rounded bg-light">
        <p><strong>@AppState!.T("Select platform simulation")</strong></p>
        <div class="d-flex flex-wrap gap-2">
            <P11Button Text="iPhone (iOS)" OnClick="() => SetDevice(NativeDevice.IPHONE)" />
            <P11Button Text="Android" OnClick="() => SetDevice(NativeDevice.ANDROID)" />
            <P11Button Text="iMac (macOS)" OnClick="() => SetDevice(NativeDevice.MAC)" />
            <P11Button Text="Web / Windows" OnClick="() => SetDevice(NativeDevice.WEB)" />
        </div>
        <div class="mt-3">
            <span class="badge bg-info text-dark p-2">@AppState!.T("Current mode:") @_currentDevice</span>
        </div>
    </div>

    @* Trigger Button *@
    <P11Button Text="Overlay open"
               HtmlType="HtmlType.Button"
               CssClass="btn-primary shadow"
               OnClick="() => _isOverlayVisible = true" />

    @* Die Overlay-Komponente *@
    <P11OverlayNative @bind-Visible="_isOverlayVisible"
                      NativeDevice="_currentDevice"
                      Title="Media preview"
                      CloseButtonText="Back"
                      CloseButtonIconCss="@GetIconForDevice()"
                      ShowHeaderSeparator="false"
                      CssClassContent="p-0">

        @* Container für Auto-Fit: 
           Wir nutzen flex-column, damit Bild und Text eine Einheit bilden.
        *@
        <div class="d-flex flex-column align-items-center justify-content-center p-3">

            @* Das Bild wird durch CSS (max-height: calc(100vh - 180px)) begrenzt *@
            <img src="https://picsum.photos/1200/800"
                 alt="Test Bild"
                 class="img-fluid rounded shadow-lg mb-3" />

            @* Text-Bereich: 
               Durch die Begrenzung des Bildes rutscht dieser Text ins Sichtfeld.
            *@
            <div class="text-white text-center" style="max-width: 700px;">
                <h5 class="text-uppercase border-bottom pb-2 d-inline-block">@_currentDevice Modus</h5>
                <p class="mt-2">
                    @switch (_currentDevice)
                    {
                        case NativeDevice.IPHONE:
                            <span><strong>iOS:</strong> Text "Back" + chevron on the left. Background is fixed.</span>
                            break;
                        case NativeDevice.ANDROID:
                            <span><strong>Android:</strong> Only the left arrow. Background scrolling is disabled.</span>
                            break;
                        case NativeDevice.MAC:
                            <span><strong>macOS:</strong> Closing via traffic light. Image scales dynamically.</span>
                            break;
                        default:
                            <span><strong>Web/Windows:</strong> White 'X' in the upper right corner. Page scrolling is not possible.</span>
                            break;
                    }
                </p>
                <p class="small text-muted mb-0">
                    Even if the text is very long, the overlay still allows scrolling within the black area.
                </p>
            </div>
        </div>

    </P11OverlayNative>
</div>

@code {
    private bool _isOverlayVisible = false;
    private NativeDevice _currentDevice = NativeDevice.WEB;

    private void SetDevice(NativeDevice device)
    {
        _currentDevice = device;
        StateHasChanged();
    }

    private string GetIconForDevice() => _currentDevice switch
    {
        NativeDevice.IPHONE => "bi bi-chevron-left",
        NativeDevice.ANDROID => "bi bi-arrow-left",
        _ => ""
    };

    private void LogEvent(string message)
    {
        Console.WriteLine($"[P11Overlay] {message}");
    }
}

Component API

Parameter	Type	Default	Description
`Visible`	`bool`	`false`	Controls the visibility of the overlay. Supports `@bind-Visible`.
`Id`	`Guid`	`Guid.Empty`	Optional stable ID. If empty, an internal ID is generated automatically.
`NativeDevice`	`NativeDevice`	`WEB`	Determines the visual platform style (iOS, Android, Mac, Web).
Content Slots
`Title`	`string?`	`null`	Text displayed in the header. Position adapts to the platform style.
`ChildContent`	`RenderFragment?`	-	The main content area of the overlay (e.g., an image or video).
Visual Configuration
`ShowHeaderSeparator`	`bool`	`false`	Toggles the visual line between header and content.
`ShowCloseButton`	`bool`	`true`	If true, a platform-specific close control is rendered.
`CloseButtonText`	`string?`	`null`	Custom text for the close button (mostly used for iOS 'Back' label).
`CloseButtonIconCss`	`string?`	`null`	Custom icon class for the close button (e.g., 'bi bi-x').
`ShowDevelopmentErrors`	`bool`	`true`	Shows validation alerts (e.g., missing ChildContent) during development.
Custom CSS
`CssClassHeader`	`string?`	`null`	Custom CSS class for the overlay header.
`CssClassContent`	`string?`	`null`	Custom CSS class for the content container (useful for 'p-0' images).
Events
`VisibleChanged`	`EventCallback<bool>`	-	Fires when visibility changes.
`OnClose`	`EventCallback`	-	Fires when the overlay is closed via button or Escape key.