• API: Null arguments throw ArgumentNullException at the call. Public and protected members of the five libraries now guard the non-nullable reference parameters they cannot handle (about 275 guards).
  • A null that used to cause a NullReferenceException later (or was stored silently) fails at the call, with a ParamName. What to do: fix the caller.
  • An async member throws from the call itself, before it returns a Task.
  • Null arguments that a member handled before are still accepted, for example an IProgress<double> or a Paint background of null.
  • Feature-specific effects are listed in each feature's section.
  • BasePlatformBehavior guards only bindable. A null platform view passes through, because the Android IconTintColorBehavior accepts it.
• Setup: CommunityToolkit.Maui.Core on Android adds a <queries> entry for the launcher (MAIN/HOME) to the app's merged manifest through the package's library manifest (src/CommunityToolkit.Maui.Core/AndroidManifest.xml). Badge needs it on Android 11 and later. If your app or Play listing reviews <queries>, check the merged manifest.
• Setup: Dependencies: on Windows, CommunityToolkit.Maui.Core references System.Speech 10.0.11 (it was 10.0.1). No action is needed unless you pin the package. This comes from #3288 on main, not from this PR.

New APIs In This Release

• Popup now declares IPaddingElement, which it already inherited from ContentView
• GravatarImageSource declares IStreamImageSource, which it already inherited from StreamImageSource, and overrides Cancel() (see GravatarImageSource, after that ApiCompat run);
• [SupportedOSPlatform("android23.0")] on the Android StatusBarBehavior (see StatusBar and StatusBarBehavior).
• DefaultPopupSettings.BackgroundColorDark and OnInitializing (#3345)
• NumericValidationBehavior.Interval (#3329)

Behavior

• AvatarView.
  • HorizontalOptions, VerticalOptions, HeightRequest, WidthRequest, Padding, Stroke, StrokeThickness and StrokeShape are no longer local values, so an implicit AvatarView Style applies (and a Border Style with ApplyToDerivedTypes).
  • An empty image source shows Text on every platform; iOS, MacCatalyst and Windows had previously showed an empty circle. Set Text to string.Empty or "" to display a blank circle.
  • The text replaces a failed or empty image only once the image has been laid out (about one layout pass later), because a GravatarImageSource asks for its picture only after its image has a size. So:
    • An AvatarView whose Gravatar failed to load while the page opened offline shows the picture again when the Email changes or a new load succeeds.
    • Such an AvatarView may show an empty circle for that one layout pass before the text.

Setup

• CommunityToolkit.Maui.Core adds a <queries> entry for the launcher (MAIN/HOME) to Android apps; Badge needs it on Android 11 and later (see All packages).

Behavior

• Badge on Windows without package identity. In an unpackaged app, Badge.SetCount writes one trace line and returns, instead of throwing a COMException that ended the app. No badge appears, so package the app if you need the taskbar badge.

• See Camera v7.0.0: https://github.com/CommunityToolkit/Maui/releases#release-7.0.0-camera

Behavior

• BackgroundColorTo and TextColorTo with a rate of 0 throw ArgumentOutOfRangeException from the call. Before, the error came later on the animation ticker and ended the app. Pass a rate above 0.

Behavior

• Android modal pages and the status bar. DialogFragmentService lays the dialog of a modal page out like the activity's window, for every status bar color.
  • On Android 11 and newer, a modal page receives the status bar inset. It must keep clear of the status bar itself, as a page in the activity's window does.
  • On Android 10 and older, a modal page also receives window insets with a transparent status bar color, where it received none.

Behavior

• DrawingView.
  • On iOS and Mac Catalyst, GetImageStream with no lines returns Stream.Null instead of throwing InvalidOperationException, and a NaN image size, or one that is infinite on both sides, throws ArgumentException. Handle Stream.Null where you caught the exception.
  • An image scaled to ImageOptions.DesiredSize has its pixel size rounded half away from zero on Android, iOS and Mac Catalyst, as Windows already did. A 1920 x 1080 target of a 411 DIP canvas gives 1920 x 934 on Android, where it gave 1919 x 934.
  • On Windows a line captures the pointer, so a line released outside the view completes with DrawingLineCompleted, a lost capture raises DrawingLineCancelled, and a second pointer no longer starts or changes a line. No action is needed unless you worked around the old behavior.

Smaller changes

• An unloaded view keeps its handler and listens again when it is loaded. DrawAction draws in a canvas state of its own.

Setup

• Windows, iOS and Mac Catalyst: UseMauiCommunityToolkit registers the Expander layout handler (see Behavior below), so keep calling it at startup. That handler keeps its own platform view even when the app sets LayoutHandler.PlatformViewFactory.

Behavior

• Expander accessibility.
  • On Windows the Expander is a Tab stop that Enter and Space toggle. UI Automation exposes it as a Button with the ExpandCollapse and Invoke patterns.
  • On Android, iOS and Mac Catalyst the header is one element for TalkBack and VoiceOver, with expand and collapse actions.
  • The Expander's internal layout now resolves to an internal ExpanderLayoutHandler, so a handler an app registers for Grid no longer applies to the Expander's internal Grid; LayoutHandler.Mapper changes still apply.
  • On Windows, iOS and Mac Catalyst, an app's LayoutHandler.PlatformViewFactory no longer creates the platform view of that layout, so the layout keeps the platform view that gives the header this support. The factory still creates the platform views of the app's other layouts, including the ones in the Expander's Header and Content, and on Android also the platform view of that layout.

Smaller changes

• Expander Direction can be changed again by bindings and Styles.

API

• Null arguments throw ArgumentNullException at the call; FileSaver and FolderPicker still return the exception in the result. (see All packages)

Behavior

• FileSaver and FolderPicker.
  • progress reports percentages from 0 to 100. It reported fractions from 0 to 1 during the copy, then a final 100, so remove any * 100 you applied.
  • A stream that cannot seek no longer fails the save; it gets only the final report.
  • On Android, a document whose provider gives no file path, such as a cloud document, is a successful save whose FilePath is its content:// URI. It used to fail with FileSaveException. Open such a path with the ContentResolver.
  • A null fileName or stream (and a null initialPath for FolderPicker) comes back as an ArgumentNullException in the result, without showing the picker.

Behavior

• GravatarImageSource.
  • The email is trimmed and lower-cased before hashing, as Gravatar requires, so mixed-case addresses now load their real image.
  • The download is fully read into a seekable stream, so on Windows the picture shows again. HttpClient.Timeout limits the whole download, and a body that fails halfway gives Stream.Null.
  • One load no longer cancels another.
  • A load that you start with CancellationToken.None never throws. Only a token that you pass and cancel makes GetStreamAsync and the default Stream function throw OperationCanceledException, instead of returning Stream.Null. .NET MAUI catches it for the loads that it cancels itself, so a view keeps the picture of the load that replaced it.
  • Cancel() ends only the loads started without a cancelable token, which then return Stream.Null. Its task always completes with true.
  • What to do: catch the exception where you call Stream or GetStreamAsync with your own token.
• GravatarImageSource in a Button.
  • The picture is requested at the smaller of the WidthRequest and HeightRequest that the Button sets, or at Gravatar's default 80 pixels, and again when those requests change. It was requested at the Button's laid-out size, so on iOS and Mac Catalyst each picture made the Button larger until it was as wide as the screen (older than this PR).
  • Image, ImageButton and AvatarView still request the size they are laid out at.
  • A Button without size requests now gets an 80-pixel picture instead of one the size of the laid-out Button: on a 420 dpi Android screen, a 30 dp icon instead of 15 dp. Set HeightRequest on the Button for a smaller picture.
  • Windows: the picture is drawn whole, at most at its natural size, and scaled down to the room the Button has for it. The Button no longer grows for it.
    • Before this change, the picture loaded on Windows only with this PR's download fix (see the GravatarImageSource change above). It was then stretched to the Button's width, and the Button clipped it to a thin band.
    • A Button whose image is above or below its text (ContentLayout Top or Bottom) needs a HeightRequest that leaves room for the picture.
    • A Button without Text needs a HeightRequest or MinimumHeightRequest. The .NET MAUI app template's Button style sets MinimumHeightRequest to 44.
    • This works around a .NET MAUI behavior: on Windows, MAUI limits a Button's picture to its natural size only when it sees the BitmapImage's ImageOpened event, which a picture decoded from a stream has already raised.

Smaller changes

• KeyboardExtensions on iOS and Windows call the platform on the UI thread. IsSoftKeyboardShowing called from another thread blocks until the UI thread answers. The tasks of HideKeyboardAsync and ShowKeyboardAsync complete once the UI thread has done the work.

API

• Null arguments: MaxLengthReachedEventArgs rejects null for its non-nullable members.

Behavior

• Keyboard dismissal. MaxLengthReachedBehavior hides the keyboard only while its own InputView has the focus, and through the view's own window. So Android no longer hides the keyboard of the view the user moved to, and the keyboard goes away in a modal page or a Popup too. No action is needed.

• See MediaElement v11.0.0: https://github.com/CommunityToolkit/Maui/releases#release-11.0.0-mediaelement

Behavior

• NavigationBar (Android). The default Color is still transparent, but it is now a plain default value, so reading the color no longer makes IsSet true. As a result:
  • A page that never set a color no longer gets one applied.
  • Clearing Color or Style gives the window back its original color.
  • From Android 15 the color is drawn as a view over the navigation bar.
  • What to do: check pages that relied on the old default.

API

• Null arguments: Options.SetPopupDefaults(null) and SetPopupOptionsDefaults(null) no longer store null.
• Null arguments: The async void PopupExtensions.ShowPopup overloads throw to the caller instead of posting the exception to the SynchronizationContext.

Behavior

• BackgroundColor is null by default, and Styles now apply. Margin, Padding, HorizontalOptions, VerticalOptions, CanBeDismissedByTappingOutsideOfPopup and BackgroundColor are now default values. 15.0.1 set them as local values in the constructor.
  • A Style can set them, and Popup.BackgroundColor reads null until something sets it.
  • A popup without a background shows DefaultPopupSettings.BackgroundColor, or in the dark theme BackgroundColorDark: black with #3345 in this release, where 15.0.1 showed white.
  • What to do: set BackgroundColor where a fixed color is needed, and check popups in the dark theme.
• Navigation that removes a popup page ends ShowPopupAsync. When navigation removes the popup page without CloseAsync, ShowPopupAsync completes and Closed is raised exactly once. Before, neither happened, and code that awaited it stayed suspended.
  • Such navigation: Shell switching to another Shell element, PopModalAsync or PopAsync called by other code, Window.Page being replaced, or Shell popping the popup out of a modal NavigationPage.
  • Both happen one dispatcher cycle after .NET MAUI has removed the popup page, so a Closed handler can show another popup.
  • The result is the existing "closed without a result" shape:
    • WasDismissedByTappingOutsideOfPopup is true. It now means "closed without a result: by tapping outside the popup, or because navigation removed it"; it is false only after CloseAsync.
    • For ShowPopupAsync<TResult>, Result is null for a reference or nullable type. Reading it for a value type such as int throws PopupResultException, as after a tap outside.
  • What to do: check WasDismissedByTappingOutsideOfPopup first. Subscribe to Closed if you must tell a tap from a navigation removal.
  • If navigation removes the page before .NET MAUI reports that it was navigated to, Closed is raised without a preceding Opened.
  • A CancellationToken used as a timeout keeps working.
  • With a Shell as the root page, CloseAsync and ClosePopupAsync of a popup shown on a modal NavigationPage close only the popup. CloseAsync used to pop the whole page and never complete, and ClosePopupAsync threw PopupBlockedException.
  • A close that finds another page on top when it runs throws PopupBlockedException and pops nothing:
    • CloseAsync, Popup.CloseAsync and ClosePopupAsync (also through IPopupService) wait for earlier popup operations. When the close finally runs, they check again that the popup is still the page on top.
    • This applies when another page was pushed above the popup in the meantime, for example a popup that ShowPopupAsync was showing, or a modal page your code pushed. They already threw PopupBlockedException and popped nothing when that page was on top at the call.
    • Before, including in 15.0.1, they popped that other page and then never completed, so no popup in the app could open or close again. In some layouts they reported the popup closed while it stayed on screen.
    • ClosePopupAsync still targets the popup that was the most recent when you called it, not the newer one. Call it again to close the newer one.
    • A tap outside the popup or the Android Back button does nothing in this case. It no longer crashes the app if that other page is already on top when the tap runs.
  • A tap outside the popup, or the Android Back button:
    • no longer crashes the app (through async void) when an earlier tap, Back or navigation has already closed the popup;
    • ignores a pop that .NET MAUI canceled, where it crashed the app (on iOS and Mac Catalyst a NavigationPage cancels a PopAsync that waited behind a navigation that failed). The popup stays open, and a later tap closes it.
• ShowPopupAsync, CloseAsync and ClosePopupAsync throw OperationCanceledException when the app cancels the navigation.
  • When the app cancels the navigation that removes a popup (a Window.ModalPopping or Application.ModalPopping handler that sets e.Cancel, or a Shell.Navigating handler that cancels), Popup.CloseAsync, Popup<T>.CloseAsync, ClosePopupAsync and IPopupService.ClosePopupAsync throw OperationCanceledException. The popup stays open and usable, Closed is not raised, and the navigation lock is released.
  • When a Shell.Navigating handler cancels the navigation that shows a popup (ShowPopupAsync of a Shell, or of a page or INavigation under a Shell root), every ShowPopupAsync overload, also through IPopupService, throws OperationCanceledException and nothing is shown.
  • Before, these calls never completed. A close that the app canceled also held the navigation lock, so no popup in the app could open or close again, and the tap outside the popup stopped working.
  • ShowPopup and the tap outside or Android Back show nothing, or do nothing, and throw nothing.
  • To tell this from your own token, catch OperationCanceledException when (!token.IsCancellationRequested).
  • A .NET MAUI limitation that this PR does not change: in a Shell whose current tab has a page pushed below the popup, a ModalPopping handler that cancels makes .NET MAUI retry the pop in a loop, so CloseAsync cannot return. Cancel in Shell.Navigating there instead.

Smaller changes

• A popup shown from OnDisappearing of a modal page that is closing appears on the page below.
• A WidthRequest or HeightRequest larger than the window is limited to the window.
• Opened is raised once per show.
• PopupClosed and Closed are raised after the navigation lock is released, in the same order as before.

Smaller changes

• RatingView redraws when FillOption changes.

API

• Null arguments: SelectAllTextBehavior on Windows throws ArgumentNullException instead of InvalidOperationException for a null platform view (only a derived class can reach it).

Behavior

• SemanticOrderView on Windows sets the Tab order. Check the Tab order of screens that use it.
  • The views of ViewOrder that the container holds are listed first in its tab focus children, followed by the rest of its content.
  • A TabIndex that the app set is no longer overwritten. The exception: views of ViewOrder that a control within the container (a ScrollView, for example) holds, or that are outside the container, still get a TabIndex from the order.
  • It does not change Narrator's scan order, which follows the visual tree.

Smaller changes

• An app's ContentViewHandler.PlatformViewFactory no longer creates the SemanticOrderView's platform view, so ViewOrder applies.
  • The factory still creates the platform views of the other content views and pages.
  • To customize that view, override CreatePlatformView in a handler derived from SemanticOrderViewHandler, and register it after UseMauiCommunityToolkit.

Behavior

• Windows Toast and Snackbar remove only their own notification. Each removes its notification by Id. No action is needed unless the app relied on the old clear-all (below).
  • Before, a Toast.Show or Toast.Dismiss after an earlier toast, and a Snackbar.Show or Snackbar.Dismiss while a snackbar was shown, removed every notification of the app (AppNotificationManager.RemoveAllAsync). That included the other alert and the notifications the app shows itself, on screen and in the Action Center.
  • Since a Show no longer clears the app's other notifications, a Toast or Snackbar shown while another notification banner of the app is on screen waits behind that banner, as Windows queues banners.
  • Show now returns once Windows lists the new notification. That takes up to 1 s longer when Windows lists nothing for the app, for example while its notifications are off. A Snackbar whose Duration is zero or less does not wait.
  • Overlapping Show and Dismiss calls now take effect in call order. A call whose token is cancelled before its turn removes nothing and throws OperationCanceledException.
  • Do not block on a Show or Dismiss Task inside a Shown or Dismissed handler: .Wait() and .Result deadlock there.

Smaller changes

• Snackbar on Windows:
  • It is dismissed at the end of Duration, raises Dismissed once and runs its action on the UI thread.
  • Show can take up to 1 s longer while the app's notifications are off (see Behavior above).
  • Show no longer throws for a Duration such as TimeSpan.MaxValue or TimeSpan.MinValue.
• Snackbar on Android: a Duration below 1 ms shows it for 1 ms, and Dismissed is raised once.
• Toast on Windows is removed at the end of Duration.

Setup

• CommunityToolkit.Maui.Core references System.Speech 10.0.11 on Windows (see All packages).

Smaller changes

• StartListenAsync with null options throws ArgumentNullException from the call (see All packages: null arguments). With valid options, a canceled token still returns a canceled Task, so awaiting it throws OperationCanceledException.
• On Windows, and for a start from a background thread on iOS and Mac Catalyst, an interrupted StartListenAsync completes without an exception and without listening, even if its token is canceled afterwards.
  • Here "interrupted" means StopListenAsync or DisposeAsync (on Windows, also a newer StartListenAsync) is called while the start waits for the platform.

Behavior

• StateContainer. A StateKey that is not defined throws StateContainerException with its own message and no inner exception. It used to throw the "assigned to multiple StateViews" message, so change any code that matches the message text.

API

• StatusBarBehavior requires Android 6.0 (API 23). The Android type is now [SupportedOSPlatform("android23.0")], like StatusBar already was.
  • C# code that uses it in a project with a lower minimum Android version (the .NET MAUI templates use 21) gets warning CA1416, which fails builds that treat warnings as errors.
  • What to do: raise the minimum Android version to 23, or create the behavior inside if (OperatingSystem.IsIOS() || OperatingSystem.IsAndroidVersionAtLeast(23)). Not IsAndroidVersionAtLeast(23) alone: it is false on iOS.
  • A StatusBarBehavior declared in XAML gets no warning.
  • Nothing changes at run time: on Android 5.0 and 5.1 it did nothing before and still does nothing.
  • CommunityToolkit.Maui's minimum Android version stays 5.0 (API 21), the same as .NET MAUI 10's.

Setup

• iOS: remove UIViewControllerBasedStatusBarAppearance from Info.plist if you set it to false for StatusBar.SetStyle (see Behavior below).
• Android: StatusBarBehavior needs a minimum Android version of 23 or a guard (see API above). CommunityToolkit.Maui's minimum Android version stays 5.0 (API 21), the same as .NET MAUI 10's.

Behavior

• iOS, .NET 10: StatusBar.SetStyle and StatusBarBehavior. SetStyle no longer needs UIViewControllerBasedStatusBarAppearance set to false in Info.plist.
  • The first LightContent or DarkContent replaces preferredStatusBarStyle until the app ends, for every view controller that does not choose its own style (the system pickers included). Default gives each view controller its own style back.
  • With the key set to false, the style still applies in apps built with an iOS SDK before 27, but not with the iOS 27 SDK (Xcode 27): the app keeps its status bar style and the call writes a trace message. So remove the key from Info.plist.
  • SetStyle called off the main thread throws UIKitThreadAccessException, in Release builds too, so call it on the main thread.

Smaller changes

• On Android 15+, colors without alpha no longer paint the bars black. On iOS, the status bar color view follows rotation and lets touches through, and on iOS 26 it comes back after an iPhone turns back to portrait.

Smaller changes

• StringToListConverter splits at the entry of a one-entry Separators list, as documented; before, it split at Separator.

Smaller changes

• Windows selects the tapped CollectionView item. On Android and Windows, a tap on a header, footer or empty view selects nothing.
• The state events are raised at once with the new value.
• ShouldMakeChildrenInputTransparent takes effect when it changes.
• A NaN DefaultOpacity, HoveredOpacity or PressedOpacity throws ArgumentOutOfRangeException, where 15.0.1 accepted it.
• On Windows, a release now ends every press, as on Android (iOS also cancels a touch for good once it has left the element). Whatever CurrentHoverStatus says, a release over the element completes the tap (Command, TouchGestureCompleted), and a release outside it cancels.
  • Before, a Windows release completed only while the hover status was Entered. So a release outside the element could complete, and one over it could leave the press running.

API

• Null arguments: The async void overrides of UserStoppedTypingBehavior throw to the caller instead of posting the exception to the SynchronizationContext.

Behavior

• Keyboard dismissal. UserStoppedTypingBehavior hides the keyboard only while its own InputView has the focus, and through the view's own window. So Android no longer hides the keyboard of the view the user moved to, and the keyboard goes away in a modal page or a Popup too. No action is needed.
• UserStoppedTypingBehavior.StoppedTypingTimeThreshold rejects a negative value. A negative value is ignored and the previous value is kept (MAUI logs a warning). Before, it failed inside Task.Delay. Use 0 or more.

API

• Null arguments: The async void overrides of ValidationBehavior throw to the caller instead of posting the exception to the SynchronizationContext.

Smaller changes

• Validation behaviors validate again when a rule changes. Errors is set on the UI thread, and IsRunning is reset after a cancel.