Using Custom Renderers in .NET MAUI

While there are many benefits to using the new handler-mapper pattern, it's still possible to use the custom renderer pattern for customizing at the platform level familiar to Xamarin.Forms developers. To demonstrate using custom renderers in .NET MAUI, let's consider this Xamarin.Forms control PressableView. The control simply exposes pressed and released events based on the platform-specific gestures. The custom renderer implementation is composed of 3 files:

• PressableView.cs - the cross-platform class that extends ContentView
• PressableViewRenderer.cs - the Android implementation
• PressableViewRenderer.cs - the iOS implementation

To use this in .NET MAUI you will:

1. Add the files into the appropriate location in your .NET MAUI project(s)
2. Modify the "usings" and files
3. Configure the renderers in MauiProgram.cs

Add the Files

If you're using the .NET MAUI multi-targeted project, the cross-platform file can be moved to anywhere outside the Platforms folder, and the platform-specific implementation files should be moved to the corresponding Platform folder.

On the other hand if you're solution has separate projects per-platform, then you would move the platform-specific implementation files into the corresponding projects.

Modify Usings and Files

Any reference to the Xamarin.Forms.* namespaces need to be removed, and then you can resolve the related types to Microsoft.Maui.*. This needs to be done in all files you've added to the .NET MAUI project(s).

Remove any ExportRenderer directives as they won't be needed in .NET MAUI, such as:

[assembly: ExportRenderer(typeof(PressableView), typeof(PressableViewRenderer))]

Configure Renderers

Open MauiProgram.cs in your .NET MAUI project, add UseMauiCompatibility() with using Microsoft.Maui.Controls.Compatibility.Hosting, and then configure each renderer using conditional compilation for each platform.

public static MauiApp CreateMauiApp()
{
	var builder = MauiApp.CreateBuilder();
	builder
		.UseMauiApp<App>()
		.UseMauiCompatibility()
                .ConfigureMauiHandlers((handlers) =>{
#if ANDROID
			handlers.AddCompatibilityRenderer(typeof(PressableView),typeof(XamarinCustomRenderer.Droid.Renderers.PressableViewRenderer));
#endif

#if IOS
                        handlers.AddCompatibilityRenderer(typeof(PressableView), typeof(XamarinCustomRenderer.iOS.Renderers.PressableViewRenderer));
#endif
        });

	return builder.Build();
}

Conclusion

That's it! You can now use your custom renderer in .NET MAUI just like any other custom control.

<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:c="clr-namespace:XamarinCustomRenderer.Controls"
             x:Class="MauiCustomRenderer.MainPage">

    <Grid BackgroundColor="#f1f1f1">
        <c:PressableView Pressed="Handle_Pressed"
                         Released="Handle_Released"
                         HorizontalOptions="Center"
                         VerticalOptions="Center">
            <Frame CornerRadius="20"
                   BackgroundColor="Transparent"
                   IsClippedToBounds="true"
                   Padding="0">
                <Grid
                    Background="#202020">

                    <Label Text="Press Me"
                           FontSize="16"
                           TextColor="White"
                           Margin="24,20"
                           HorizontalTextAlignment="Center" />
                </Grid>
            </Frame>
        </c:PressableView>
    </Grid>

</ContentPage>