Plugin.Maui.Popup 2.0.1-preview1

Plugin.Maui.Popup

High-performance, platform-native popups for .NET MAUI. Uses native overlays (Android Dialog, iOS/Mac Catalyst UIView, Windows WinUI Popup) instead of modal navigation for faster popup display.

Sample App

Check out the SampleApp in this repo for a full working demo of all features — CornerRadius, ContentPadding, AutoCloseAfter, CloseAllPopups, OnDismissed event, animations, layouts, and more.

Installation

Available on NuGet: https://www.nuget.org/packages/Plugin.Maui.Popup

dotnet add package Plugin.Maui.Popup

Pre-release: 2.0.1-preview1

dotnet add package Plugin.Maui.Popup --version 2.0.1-preview1

Fixes in 2.0.1-preview1:

• OnAppearing() / OnDisappearing() overrides on a BasePopupPage now fire correctly on the native popup path. Previously they were no-ops because the popup is rendered outside the MAUI visual tree, where MAUI's lifecycle dispatch is gated on Parent/Window being non-null.

If you'd been working around this by initializing in the constructor, you can now move that logic to OnAppearing() as expected.

Supported Platforms

Quick Start

1. Create a Popup Page

Add the MAUI Popup namespace and replace the ContentPage tag with BasePopupPage:

MyPopup.xaml

<?xml version="1.0" encoding="utf-8" ?>
<mauiPopup:BasePopupPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:mauiPopup="clr-namespace:MauiPopup.Views;assembly=MauiPopup"
             x:Class="MyApp.MyPopup">
    <VerticalStackLayout Padding="20" Spacing="15" WidthRequest="300">
        <Label Text="Hello from Popup!"
               FontSize="20" FontAttributes="Bold"
               HorizontalOptions="Center" />
        <Button Text="Close" Clicked="OnCloseClicked" />
    </VerticalStackLayout>
</mauiPopup:BasePopupPage>

MyPopup.xaml.cs

using MauiPopup;
using MauiPopup.Views;

namespace MyApp;

public partial class MyPopup : BasePopupPage
{
    public MyPopup()
    {
        InitializeComponent();
    }

    private async void OnCloseClicked(object sender, EventArgs e)
    {
        await PopupAction.ClosePopup();
    }
}

2. Show the Popup

using MauiPopup;

// Simple popup (no return value)
await PopupAction.DisplayPopup(new MyPopup());

3. Close the Popup

// Close with no value
await PopupAction.ClosePopup();

// Close with a return value
await PopupAction.ClosePopup("some result");

Return Values

You can get values back from a popup when it closes.

Return a string:

string result = await PopupAction.DisplayPopup(new MyPopup());

Return a typed object:

var user = await PopupAction.DisplayPopup<UserInfo>(new MyPopup());

Close with value (from inside the popup):

await PopupAction.ClosePopup(new UserInfo { Name = "John", Age = 30 });

Close All Popups

Close every open popup at once — useful for navigation changes or logout scenarios.

await PopupAction.CloseAllPopups();

Check If Popup Is Open

bool isOpen = PopupAction.IsPopupOpen;

Properties

All properties are BindableProperty and can be set in XAML or code-behind.

Color Properties

var popup = new MyPopup();
popup.ForegroundColor = Colors.LightBlue;
popup.OverlayColor = Color.FromArgb("#CC000000"); // 80% black overlay

Layout Properties

Position examples:

// Center (default)
popup.VerticalOptions = LayoutOptions.Center;
popup.HorizontalOptions = LayoutOptions.Center;

// Bottom sheet
popup.VerticalOptions = LayoutOptions.End;
popup.HorizontalOptions = LayoutOptions.Fill;

// Top notification banner
popup.VerticalOptions = LayoutOptions.Start;
popup.HorizontalOptions = LayoutOptions.Fill;
popup.Margin = new Thickness(10, 50, 10, 0);

CornerRadius:

// Uniform radius
popup.CornerRadius = new CornerRadius(20);

// Top corners only (great for bottom sheets)
popup.CornerRadius = new CornerRadius(20, 20, 0, 0);

// Per-corner: TopLeft, TopRight, BottomRight, BottomLeft
popup.CornerRadius = new CornerRadius(10, 20, 10, 20);

ContentPadding:

// Uniform padding
popup.ContentPadding = new Thickness(16);

// Horizontal and vertical
popup.ContentPadding = new Thickness(20, 30);

// Per-side: Left, Top, Right, Bottom
popup.ContentPadding = new Thickness(10, 30, 10, 30);

Animation Properties

Available animations:

popup.Animation = PopupAnimation.SlideUp;
popup.AnimationDuration = 300;

Behavior Properties

Auto-close:

// Auto-close after 3 seconds
popup.AutoCloseAfter = TimeSpan.FromSeconds(3);

// Timer is automatically cancelled if the user closes manually

Prevent background dismiss (for required input):

popup.IsCloseOnBackgroundClick = false;

Events

Dismissed Event

Fires when the popup is closed, providing the return value.

var popup = new MyPopup();
popup.Dismissed += (sender, args) =>
{
    var result = args.Result;
    Console.WriteLine($"Popup dismissed with: {result}");
};
await PopupAction.DisplayPopup(popup);

You can also override the OnDismissed method in your popup subclass:

public partial class MyPopup : BasePopupPage
{
    protected override void OnDismissed(PopupDismissedEventArgs e)
    {
        base.OnDismissed(e);
        // Custom dismiss logic here
    }
}

Lifecycle Methods

Override OnAppearing() and OnDisappearing() on your popup the same way you would on a regular ContentPage:

public partial class MyPopup : BasePopupPage
{
    public MyPopup()
    {
        InitializeComponent();
    }

    protected override void OnAppearing()
    {
        base.OnAppearing();
        // Runs every time the popup becomes visible.
        // Good for: starting timers, refreshing data, focusing inputs.
    }

    protected override void OnDisappearing()
    {
        base.OnDisappearing();
        // Runs every time the popup is dismissed.
        // Good for: stopping timers, saving state, releasing resources.
    }
}

Note on events vs. overrides: The plugin invokes the protected OnAppearing() / OnDisappearing() virtuals directly. The Page.Appearing / Page.Disappearing events (the ones you'd subscribe to with popup.Appearing += ...) are not raised on the native popup path, because the popup page lives outside the MAUI visual tree. Use the override pattern shown above instead.

Dark Mode Support

BasePopupPage automatically adapts to the system theme:

• Light mode — white popup background
• Dark mode — dark (#282828) popup background

You can override these by setting ForegroundColor and OverlayColor explicitly.

Common Patterns

Bottom Sheet

var popup = new MyPopup
{
    VerticalOptions = LayoutOptions.End,
    HorizontalOptions = LayoutOptions.Fill,
    Margin = new Thickness(0),
    CornerRadius = new CornerRadius(20, 20, 0, 0),
    ContentPadding = new Thickness(20),
    Animation = PopupAnimation.SlideUp
};

Toast / Notification Banner

var popup = new MyPopup
{
    VerticalOptions = LayoutOptions.Start,
    HorizontalOptions = LayoutOptions.Fill,
    Margin = new Thickness(10, 50, 10, 0),
    CornerRadius = new CornerRadius(12),
    ContentPadding = new Thickness(16),
    Animation = PopupAnimation.SlideDown,
    AutoCloseAfter = TimeSpan.FromSeconds(3),
    ForegroundColor = Color.FromArgb("#4CAF50")
};

Confirm Dialog

var popup = new ConfirmPopup
{
    IsCloseOnBackgroundClick = false,
    CornerRadius = new CornerRadius(16),
    ContentPadding = new Thickness(20),
    Animation = PopupAnimation.Scale
};
bool confirmed = await PopupAction.DisplayPopup<bool>(popup);

Full Page Popup

var popup = new MyPopup
{
    VerticalOptions = LayoutOptions.Fill,
    HorizontalOptions = LayoutOptions.Fill,
    Margin = new Thickness(0),
    IsCloseOnBackgroundClick = false,
    Animation = PopupAnimation.Scale
};

API Reference

PopupAction (Static Methods)

BasePopupPage (Properties)

BasePopupPage (Events)

PopupDismissedEventArgs