.NET MAUI Tips - Some Dos and Don'ts

Use Shell or TabbedPage|FlyoutPage|NavigationPage

NOT BOTH

The combination is unsupported.

Set MainPage once

or YMMV

Consider instead how you can craft different configurations within AppShell.xaml.

Don't nest tabs (TabbedPage > TabbedPage)

Instead evaluate the UX and consider a different, standard approach

Reference MauiImages as PNG

(not svg)

<Image Source="dotnet_bot.png" />

The svg is only a source file that generates PNGs at the target densities and sizes.

If you need SVG, use SkiaSharp or a library like Vapolia.Svg

Don’t nest unconstrained scrolling things inside a stack layout.

• unconstrained - it has no explicit sizing constraints like WidthRequest, HeightRequest, or the parent container size may be unknown
• scrolling things - like CollectionView, ListView, and ScrollView
• stack layout - including StackLayout, HorizontalStackLayout, and VerticalStackLayout

A VerticalStackLayout hosting an unsized/unconstrained vertical scrollable control will not scroll or virtualize unless the height is constrained.

If the layout/scroll directions are not aligned, then it’ll work (e.g. vertical layout with a horizontal scrolling child).

Customize handlers in ConfigureHandlers()

Append/Modify etc. only run once and should be in place before the first handlers are created.

ConfigureHandlers is a builder method in MauiProgram.cs.

Don’t nest elements with gesture recognizers

A control with gesture recognizers inside of a layout with gesture recognizers is a recipe for problems.

Similarly, beware z-index issues when implementing gestures where views overlap. Use InputTransparent to ensure gestures pass through views when necessary.

Move simple renderers to handler modifications (Append/Modify)

While a renderer can be wired up in .NET MAUI, handlers are preferred.

Much simpler to implement and maintain long term.

Rewrite custom controls (renderers) as handlers with mappers

Wiring up a renderer is a quick start during migration, but you may find porting the implementation to a handler faster and more reliable.

Start with wiring the handler, but don’t spend too long on it if it doesn’t work.

Prefer Grid with explicit size and * in DataTemplates

Use of Auto, and use of stack layouts inside DataTemplates are less reliable for measure/layout.

Ask Ben Buttigieg for more info ;)

Use MauiSplashScreen and MauiIcon only for the simple cases

Use native implementations for anything more complex if those don't immediately meet your needs.

Prefer ProjectReference over NuGets for sharing your libraries

Safer, easier, and sharing more things is supported.