Popup V2 #1581

bijington · 2023-11-29T21:46:51Z

Description of Change

Popup v2 completely redesigns Popup from the ground up. Instead of using custom handlers to create a Popup, instead of using janky workarounds to display the popup, and instead of using janky workarounds to size + position the Popup, Popup now inherits from ContentView and is displayed using a Transparent Modal Page.

Under the hood, we've created internal class PopupPage : Content, a transparent ContentPage that is used to display content. When ShowPopupAsync() is called, we now use the MAUI's INavigation to display the Popup on a PopupPage using await Navigation.PushModalAsync(popupPage, shouldAnimate: false).

There are also now 2 ways user can create popup:

Create custom control inheriting from Popup
Pass in a View directly to ShowPopup
- e.g. Shell.Current.ShowPopup(new Label { Text = "This is a Popup" })

For MVVM users there is a PopupService. Pay attention all popups must be registered. Also you can close popup from PopupService only if you opened it using PopupService. DO NOT combine extension method and PopupService.

Now all configurations live in PopupOptions. You can configure PageOverlayColor, Shadow, Border, BorderThickness, BorderStrokeThickness and CanBeClosedByTappingOutsidePopup.

The BindingContext is set automatically to PopupContainer, Popup and View.

As the new Popup uses only MAUI Controls, we expect you get all benefits of HotReload. All Controls including Popup in Popup and MediaElement should work without issues.

Features removed: AnchorView.

Linked Issues

PR Checklist

Has a linked Issue, and the Issue has been approved(bug) or Championed (feature/proposal)
Has tests (if omitted, state reason in description)
Has samples (if omitted, state reason in description)
Rebased on top of main at time of PR
Changes adhere to coding standard
Documentation created or updated: Feature/maui/sl popup v2 MicrosoftDocs/CommunityToolkit#552

Migration Guide

Popup XAML/CS

Remove CanBeDismissedByTappingOutsideOfPopup and pass parameter using PopupOptions
Color is replaced with Background Color
Size is replaced with WidthRequest and HeightRequest

You can now use any View as Popup Content without inheriting it from Popup. But if you need to return a result from the popup, you have to inherit from Popup.

Popup Service

All popup configurations can be configured using PopupOptions and passed as a parameter
You need to pass INavigation to make sure the popup is displayed on the correct window.

ne0rrmatrix · 2023-12-01T02:39:34Z

I have ended up rewriting at least 3 or 4 samples submitted as bugs using standard DI pattern because the code would crash in IOS 17.x. I wanted to verify the issues that were being reported. If I see a bunch of different reports I put extra effort in.

Simplifying implementation would be great. I am all for that.

src/CommunityToolkit.Maui/PopupService.cs

bijington · 2024-02-11T14:20:37Z

There are currently a couple of breaking changes to the IPopupService that I think are still good but we should consider documenting them to aid developers upgrading:

await popupService.ShowPopupAsync<MockPageViewModel>(CancellationToken.None);

becomes

await popupService.ShowPopupAsync<MockPageViewModel>(token: CancellationToken.None);

await Assert.ThrowsAsync<TaskCanceledException>(() => popupService.ShowPopupAsync<MockPageViewModel>(viewModel => viewModel.HasLoaded = true, cts.Token));

becomes

await Assert.ThrowsAsync<TaskCanceledException>(() => popupService.ShowPopupAsync<MockPageViewModel>(viewModel => viewModel.HasLoaded = true, token: cts.Token));

It also involves removing the ability to supply a viewModel instance to the Show methods to remove the confusion we have seen around developers expecting the BindingContext to automatically be set. I am happy to move this into a separate PR if we think it if worthwhile?

TheCodeTraveler · 2024-03-26T00:34:49Z

@bijington FYI - we now have a few merge conflicts on this PR after merging a bunch of Popup PRs today

Copilot

Copilot reviewed 5 out of 11 changed files in this pull request and generated no suggestions.

Files not reviewed (6)

samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml: Language not supported
samples/CommunityToolkit.Maui.Sample/Views/Popups/PopupContentView.xaml: Language not supported
samples/CommunityToolkit.Maui.Sample/MauiProgram.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/MultiplePopupViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/PopupContentViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/Views/Popups/PopupContentView.xaml.cs: Evaluated as low risk

pictos

Good job! I didn't run locally yet, just reviewed the code.

I saw that you removed the old popups reference, and I think we should mark them as obsolete and let them live for a while before removing everything. At least is what I remember from the last standup.

src/CommunityToolkit.Maui/Views/Popup/PopupContainer.cs

src/CommunityToolkit.Maui/Views/Popup/PopupExtensions.cs

src/CommunityToolkit.Maui/Views/Popup/PopupService.cs

Copilot

Copilot reviewed 81 out of 96 changed files in this pull request and generated no comments.

Files not reviewed (15)

samples/CommunityToolkit.Maui.Sample/App.xaml: Language not supported
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/MultiplePopupPage.xaml: Language not supported
samples/CommunityToolkit.Maui.Sample/Resources/Styles/Styles.xaml: Language not supported
samples/CommunityToolkit.Maui.Sample/Models/PopupSize.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/AppShell.xaml.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/PopupSizingIssuesViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/StylePopupViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/PopupPositionViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/CustomSizeAndPositionPopupViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/UpdatingPopupViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/Pages/Views/MediaElement/MediaElementPage.xaml.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupLayoutAlignmentPage.xaml.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/ShowPopupInOnAppearingPage.xaml.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/ViewsGalleryViewModel.cs: Evaluated as low risk
samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/PopupAnchorViewModel.cs: Evaluated as low risk

Comments suppressed due to low confidence (1)

samples/CommunityToolkit.Maui.Sample/ViewModels/Views/Popup/PopupContentViewModel.cs:8

The property name 'message' should be renamed to 'Message' to follow PascalCase convention.

string message = "";

bijington · 2025-05-21T15:33:06Z

This PR is also extremely close to merging. I'm working on the docs this week which is the final hurdle

Handlers re-added with [Obsolete]. We will remove them in the .NET 10 PR.

Copilot

Pull Request Overview

This PR refactors the popup samples to use the new IPopupService API (Popup V2), removes legacy popup pages, and updates popup configuration property names, service registrations, and styles for compatibility with MAUI Toolkit Popup V2.

Replace direct ShowPopupAsync extension and PopupSizeConstants usage with IPopupService injection across sample pages.
Remove obsolete sample pages (PopupAnchorPage, MultiplePopupPage, CustomSizeAndPositionPopupPage) and update navigation routes to the consolidated PopupsPage.
Update PopupOptions property names (e.g., WidthRequest, HeightRequest, BackgroundColor), bump package and MAUI versions, and refresh service registrations for new popups.

Reviewed Changes

Copilot reviewed 137 out of 137 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/ShowPopupInOnAppearingPage.xaml.cs	Inject `IPopupService`, track single display with flag
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupsPage.xaml.cs	Inject `IPopupService`, consolidate handlers into `PopupsPage`
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupSizingIssuesPage.xaml	Rename title, remove obsolete `CommandParameter` binding
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupLayoutAlignmentPage.xaml.cs	Update layout option logic; switch to `ShowPopup` call
samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupOnDisappearingPage.cs	Switch to inline `ShowPopupAsync` on disappearing
samples/CommunityToolkit.Maui.Sample/MauiProgram.cs	Remove `PopupSizeConstants`, overhaul popup registrations
samples/CommunityToolkit.Maui.Sample/CommunityToolkit.Maui.Sample.csproj	Bump toolkit and resilience package versions
samples/CommunityToolkit.Maui.Sample/AppShell.xaml.cs	Update shell route mappings for new popup pages
samples/CommunityToolkit.Maui.Sample/App.xaml	Migrate popup style setters to new property names
Directory.Build.props	Bump MAUI package version and suppress new analyzer ID

Comments suppressed due to low confidence (3)

samples/CommunityToolkit.Maui.Sample/MauiProgram.cs:125

IPopupService is injected into several pages but not registered in the DI container. Add a registration like builder.Services.AddSingleton<IPopupService, PopupService>(); before consuming it.

builder.Services.AddSingleton<AppShell>();

samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/ShowPopupInOnAppearingPage.xaml.cs:9

[nitpick] Private fields should follow .NET conventions by being prefixed with an underscore. Consider renaming hasPopupBeenShown to _hasPopupBeenShown.

bool hasPopupBeenShown;

samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupSizingIssuesPage.xaml:25

The CommandParameter binding was removed but ShowPopupCommand likely needs the page reference for anchoring the popup. If the view model still depends on a parameter, either restore the CommandParameter="{Binding Source={x:Reference Self}}" or update the command implementation to no longer require an argument.

<Button Text="Show Popup" Command="{Binding ShowPopupCommand}"/>

samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupLayoutAlignmentPage.xaml.cs

…sure PopupDefaults are set

This ensures we do not forget to remove the Obsolete Popup classes in our .NET 10 release

src/CommunityToolkit.Maui.Core/Interfaces/IPopup.shared.cs

* Add `Close()` * Update PopupExtensions.shared.cs * Add CancellationToken * Add Unit Tests * Add Support for Shell * Add .NET 10 Compiler Error This ensures we do not forget to remove the Obsolete Popup classes in our .NET 10 release * Rename `Close()` -> `CloseAsync()` * Add `[EditorBrowsable(EditorBrowsableState.Never)]` to Obsolete classes * Update Samples * Fix XML

TheCodeTraveler · 2025-05-26T20:32:35Z

Here are the updated Requirements we'll add to the next Release Notes:

Breaking Changes

Popup.Anchor feature removed

Requirements

The following tools are now required for CommunityToolkit.Maui:

Download/install .NET SDK v9.0.300
Install Xcode 16.2.0 (or higher)
- Read the latest .NET MAUI Release wiki to always find the latest-supported version) of Xcode for .NET MAUI
- We HIGHLY recommend using the open-source tool Xcodes to easily manage your installed Xcode versions
Update to the latest stable version of Visual Studio (or Jet Brains Rider)
After installing the latest stable .NET SDK, update to the latest stable version of the .NET MAUI workload:
- On macOS, open the Terminal and enter the following command: sudo dotnet workload install maui; sudo dotnet workload update
- On Windows, open the command prompt (or Powershell) and enter the following command: dotnet workload install maui & dotnet workload update
Add a global.json file to your application with the following parameters to ensure you're not using a unsupported preview version of .NET (example below)
- The .NET MAUI Community Toolkit does not support preview releases of .NET

global.json

{
  "sdk": {
    "version": "9.0.300", 
    "rollForward": "latestFeature",
    "allowPrerelease": false
  }
}

bijington added the needs discussion Discuss it on the next Monthly standup label Dec 5, 2023

TheCodeTraveler removed the needs discussion Discuss it on the next Monthly standup label Jan 4, 2024

VladislavAntonyuk reviewed Feb 8, 2024

View reviewed changes

src/CommunityToolkit.Maui/PopupService.cs Outdated Show resolved Hide resolved

bijington marked this pull request as ready for review February 11, 2024 14:26

dotnet-policy-service bot added stale The author has not responded in over 30 days help wanted This proposal has been approved and is ready to be implemented labels Apr 27, 2024

bijington removed help wanted This proposal has been approved and is ready to be implemented stale The author has not responded in over 30 days labels Jun 5, 2024

bijington requested a review from a team June 9, 2024 20:43

bijington changed the title ~~Initial musings on showing popups without having to subclass Popup~~ Provide the ability to show popups without having to subclass Popup Jun 20, 2024

dotnet-policy-service bot added stale The author has not responded in over 30 days help wanted This proposal has been approved and is ready to be implemented labels Jul 22, 2024

bijington requested review from pictos and VladislavAntonyuk October 15, 2024 18:31

VladislavAntonyuk previously approved these changes Oct 30, 2024

View reviewed changes

VladislavAntonyuk requested a review from Copilot December 10, 2024 23:13

Copilot AI reviewed Dec 10, 2024

View reviewed changes

VladislavAntonyuk dismissed their stale review via 49da03d January 14, 2025 12:19

VladislavAntonyuk force-pushed the feature/sl/remove-popup-constraint-from-popup-service branch from c1488d0 to ebc39f2 Compare January 15, 2025 00:11

VladislavAntonyuk self-assigned this Jan 15, 2025

VladislavAntonyuk force-pushed the feature/sl/remove-popup-constraint-from-popup-service branch from aeb9020 to 94bee57 Compare January 15, 2025 18:52

pictos requested changes Jan 15, 2025

View reviewed changes

VladislavAntonyuk requested a review from Copilot January 15, 2025 20:31

Copilot AI reviewed Jan 15, 2025

View reviewed changes

VladislavAntonyuk added pending documentation This feature requires documentation and removed help wanted This proposal has been approved and is ready to be implemented stale The author has not responded in over 30 days labels Jan 15, 2025

TheCodeTraveler added 4 commits May 25, 2025 12:30

Re-add Handlers with [Obsolete]

c508478

Remove Microsoft.NET.Test.Sdk

7208d05

dotnet format

ac4eb1b

Update PopupResultException

4478f1e

Update NuGet Packages

b080f53

TheCodeTraveler requested a review from Copilot May 25, 2025 20:41

Copilot AI reviewed May 25, 2025

View reviewed changes

samples/CommunityToolkit.Maui.Sample/Pages/Views/Popup/PopupLayoutAlignmentPage.xaml.cs Show resolved Hide resolved

TheCodeTraveler added 4 commits May 25, 2025 13:52

Fix formatting

6fbff84

Use PopupDefaults.Padding when Padding is not set

2bcc042

Add HorizontalOptionsConverter and VerticalOptionsConverter to en…

311bd81

…sure PopupDefaults are set

Remove LayoutOptions.Fill from PopupLayoutAlignmentPage

67f453f

TheCodeTraveler mentioned this pull request May 25, 2025

Add PopupExtensions.ClosePopup() #2671

Merged

5 tasks

TheCodeTraveler added 2 commits May 25, 2025 15:59

Add ShowPopupAsync_WithViewType_SetsCorrectDefaults

a951a42

Add .NET 10 Compiler Error

7eefd49

This ensures we do not forget to remove the Obsolete Popup classes in our .NET 10 release

pictos reviewed May 26, 2025

View reviewed changes

src/CommunityToolkit.Maui.Core/Interfaces/IPopup.shared.cs Outdated Show resolved Hide resolved

TheCodeTraveler added 5 commits May 26, 2025 12:36

Add [EditorBrowsable(EditorBrowsableState.Never)] to Obsolete classes

e54a8f9

Use async/await

d1dfc66

Rename to CloseAsync

e1808e5

Bump TOOLKIT_NET_VERSION to 9.0.300

6e08a1d

TheCodeTraveler added 2 commits May 26, 2025 13:37

Update global.json

e41d330

Add Page Overloads to IPopupService

d2b499b

TheCodeTraveler merged commit 0bc2572 into main May 26, 2025
8 of 10 checks passed

TheCodeTraveler deleted the feature/sl/remove-popup-constraint-from-popup-service branch May 26, 2025 22:23

github-actions bot locked and limited conversation to collaborators May 28, 2025

This was linked to issues May 29, 2025

SwipeView inside Popup crashes on Windows with System.AccessViolationException #1904

Closed

[BUG] Media Element Popup restore from Full Screen CTD #2252

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Popup V2 #1581

Popup V2 #1581

Uh oh!

bijington commented Nov 29, 2023 •

edited by TheCodeTraveler

Loading

Uh oh!

ne0rrmatrix commented Dec 1, 2023 •

edited

Loading

Uh oh!

Uh oh!

bijington commented Feb 11, 2024

Uh oh!

TheCodeTraveler commented Mar 26, 2024

Uh oh!

Copilot AI left a comment

Uh oh!

pictos left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

bijington commented May 21, 2025

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

TheCodeTraveler commented May 26, 2025

Uh oh!

Uh oh!

Uh oh!

Popup V2 #1581

Popup V2 #1581

Uh oh!

Conversation

bijington commented Nov 29, 2023 • edited by TheCodeTraveler Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description of Change

Linked Issues

PR Checklist

Migration Guide

Popup XAML/CS

Popup Service

Uh oh!

ne0rrmatrix commented Dec 1, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

bijington commented Feb 11, 2024

Uh oh!

TheCodeTraveler commented Mar 26, 2024

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

pictos left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

bijington commented May 21, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

TheCodeTraveler commented May 26, 2025

Breaking Changes

Requirements

global.json

Uh oh!

Uh oh!

Uh oh!

bijington commented Nov 29, 2023 •

edited by TheCodeTraveler

Loading

ne0rrmatrix commented Dec 1, 2023 •

edited

Loading