.Net Maui Custom Renderers Vs Handlers Complete Guide

Custom Renderers in Xamarin.Forms

First, let's revisit how custom renderers work in Xamarin.Forms, as this will serve as our starting point.

Problem: Customizing a Button Appearance

Let's say we want to create a custom button that has a different border color and rounded corners.

Step 1: Define a Custom Button in Shared Code

In your shared project, create a new class named BorderlessButton that inherits from Button.

using Xamarin.Forms;

namespace MyXamarinApp.Controls
{
    public class BorderlessButton : Button
    {
        public BorderlessButton()
        {
            BackgroundColor = Color.LightGray;
            BorderColor = Color.Gray;
            BorderWidth = 2;
            CornerRadius = 5;
        }
    }
}

Step 2: Create a Custom Renderer for Android

In the Android project, create a class that inherits from the ButtonRenderer class and override the OnElementChanged method.

using Android.Content;
using Android.Graphics.Drawables;
using Android.Runtime;
using Android.Widget;
using MyXamarinApp.Controls;
using MyXamarinApp.Droid.Renderers;
using Xamarin.Forms;
using Xamarin.Forms.Platform.Android;

[assembly: ExportRenderer(typeof(BorderlessButton), typeof(BorderlessButtonRenderer))]
namespace MyXamarinApp.Droid.Renderers
{
    public class BorderlessButtonRenderer : ButtonRenderer
    {
        public BorderlessButtonRenderer(Context context) : base(context)
        {
        }

        protected override void OnElementChanged(ElementChangedEventArgs<Button> e)
        {
            base.OnElementChanged(e);

            if (e.OldElement != null || Element == null)
            {
                return;
            }

            GradientDrawable drawable = new GradientDrawable();
            drawable.SetCornerRadius(5 * Resources.DisplayMetrics.Density);
            drawable.SetColor(Element.BackgroundColor.ToAndroid());
            drawable.SetStroke((int)Element.BorderWidth, Element.BorderColor.ToAndroid());

            Control.Background = drawable;
        }
    }
}

Step 3: Create a Custom Renderer for iOS

Similarly, in the iOS project, create a class that inherits from ButtonRenderer and override the OnElementChanged method.

using CoreGraphics;
using MyXamarinApp.Controls;
using MyXamarinApp.iOS.Renderers;
using UIKit;
using Xamarin.Forms;
using Xamarin.Forms.Platform.iOS;

[assembly: ExportRenderer(typeof(BorderlessButton), typeof(BorderlessButtonRenderer))]
namespace MyXamarinApp.iOS.Renderers
{
    public class BorderlessButtonRenderer : ButtonRenderer
    {
        protected override void OnElementChanged(ElementChangedEventArgs<Button> e)
        {
            base.OnElementChanged(e);

            if (e.OldElement != null || Element == null)
            {
                return;
            }

            Layer.BorderColor = Element.BorderColor.ToCGColor();
            Layer.BorderWidth = (nfloat)Element.BorderWidth;
            Layer.CornerRadius = (nfloat)Element.CornerRadius;
        }
    }
}

Step 4: Use the Custom Button in XAML

Now, you can use your BorderlessButton inside XAML like this:

<?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:local="clr-namespace:MyXamarinApp.Controls"
             x:Class="MyXamarinApp.MainPage">
    <StackLayout>
        <local:BorderlessButton Text="Custom Button" />
    </StackLayout>
</ContentPage>

Custom Handlers in .NET MAUI

Now let's achieve the same functionality using custom handlers in .NET MAUI, which provide a more flexible and maintainable approach.

Problem: Customizing a Button Appearance

Let's create a custom button with the same appearance as before using handlers in .NET MAUI.

Step 1: Define a Custom Button in Shared Code

In your shared project, create a new class named CustomBorderlessButton that inherits from Button.

using Microsoft.Maui.Controls;

namespace MyMauiApp.Controls
{
    public class CustomBorderlessButton : Button
    {
        public CustomBorderlessButton()
        {
            BackgroundColor = Colors.LightGray;
            BorderColor = Colors.Gray;
            BorderWidth = 2;
            CornerRadius = 5;
        }
    }
}

Step 2: Create a Custom Handler for Android

In the Android project, create a class that derives from ButtonHandler and override the appropriate method to apply customizations.

using Android.Content;
using Android.Graphics.Drawables;
using Android.Widget;
using Microsoft.Maui.Controls;
using Microsoft.Maui.Controls.Handlers.Compatibility;
using Microsoft.Maui.Platform;
using MyMauiApp.Controls;
using MyMauiApp.Platforms.Android.Renderers;

[assembly: Android.Maui.Controls.Compatibility.ExportRenderer(typeof(CustomBorderlessButton), typeof(CustomBorderlessButtonRenderer))]
namespace MyMauiApp.Platforms.Android.Renderers
{
    public class CustomBorderlessButtonRenderer : ButtonRenderer
    {
        public CustomBorderlessButtonRenderer(Context context) : base(context)
        {
        }

        protected override void OnElementChanged(ElementChangedEventArgs<Button> e)
        {
            base.OnElementChanged(e);

            if (e.OldElement != null || Element == null)
            {
                return;
            }

            GradientDrawable drawable = new GradientDrawable();
            drawable.SetCornerRadius(5 * Context.Resources.DisplayMetrics.Density);
            drawable.SetColor(Element.BackgroundColor.ToAndroid());
            drawable.SetStroke((int)Element.BorderWidth, Element.BorderColor.ToAndroid());

            Control.Background = drawable;
        }
    }
}

Note: In .NET MAUI, you can still use the ButtonRenderer and ExportRenderer for compatibility, but we'll also show the new handlers approach. The above example is for compatibility. Now let's create the actual handler.

Step 3: Create a Custom Handler for .NET MAUI

Create a class that derives from ButtonHandler and override the ConnectHandler and DisconnectHandler methods.

using Android.Content;
using Android.Graphics.Drawables;
using Android.Widget;
using Microsoft.Maui.Controls;
using Microsoft.Maui.Controls.Platform;
using Microsoft.Maui.Platform;
using MyMauiApp.Controls;
using Android.Runtime;
using Android.OS;
using System;

namespace MyMauiApp.Platforms.Android.Handlers
{
    public class CustomBorderlessButtonHandler : ButtonHandler
    {
        protected override TextView CreatePlatformView()
        {
            Context context = Platform.CurrentActivity;
            var button = new Button(context);

            // Set any default properties here if needed
            return button;
        }

        protected override void ConnectHandler(TextView platformView)
        {
            base.ConnectHandler(platformView);
            UpdateVisualProperties(platformView, VirtualView);
        }

        protected override void DisconnectHandler(TextView platformView)
        {
            base.DisconnectHandler(platformView);
        }

        protected override void OnMapBackgroundColor(TextView platformView, Button virtualView)
        {
            base.OnMapBackgroundColor(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapBorderColor(TextView platformView, Button virtualView)
        {
            base.OnMapBorderColor(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapBorderWidth(TextView platformView, Button virtualView)
        {
            base.OnMapBorderWidth(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapCornerRadius(TextView platformView, Button virtualView)
        {
            base.OnMapCornerRadius(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        private void UpdateVisualProperties(TextView button, Button view)
        {
            if (button == null || view == null)
                return;

            GradientDrawable drawable = new GradientDrawable();
            drawable.SetCornerRadius((int)(view.CornerRadius * button.Context.Resources.DisplayMetrics.Density));
            drawable.SetColor(view.BackgroundColor.ToAndroid());
            drawable.SetStroke((int)view.BorderWidth, view.BorderColor.ToAndroid());

            button.Background = drawable;
        }
    }
}

Register the custom handler in your MauiProgram.cs file:

using Microsoft.Maui.Handlers;
using MyMauiApp.Platforms.Android.Handlers;
using MyMauiApp.Controls;

namespace MyMauiApp
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                });

            builder.ConfigureMauiHandlers(handlers =>
            {
                handlers.AddHandler<CustomBorderlessButton, CustomBorderlessButtonHandler>();
            });

            return builder.Build();
        }
    }
}

Repeat the same steps for iOS:

Step 4: Create a Custom Handler for iOS

Create a class that derives from ButtonHandler and override the corresponding methods.

using CoreGraphics;
using UIKit;
using MyMauiApp.Controls;
using Microsoft.Maui.Controls;
using Microsoft.Maui.Controls.Platform;
using Microsoft.Maui.Platform;

namespace MyMauiApp.Platforms.iOS.Handlers
{
    public class CustomBorderlessButtonHandler : ButtonHandler
    {
        protected override UIButton CreatePlatformView()
        {
            return new UIButton(UIButtonType.System);
        }

        protected override void ConnectHandler(UIButton platformView)
        {
            base.ConnectHandler(platformView);
            UpdateVisualProperties(platformView, VirtualView);
        }

        protected override void DisconnectHandler(UIButton platformView)
        {
            base.DisconnectHandler(platformView);
        }

        protected override void OnMapBackgroundColor(UIButton platformView, Button virtualView)
        {
            base.OnMapBackgroundColor(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapBorderColor(UIButton platformView, Button virtualView)
        {
            base.OnMapBorderColor(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapBorderWidth(UIButton platformView, Button virtualView)
        {
            base.OnMapBorderWidth(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        protected override void OnMapCornerRadius(UIButton platformView, Button virtualView)
        {
            base.OnMapCornerRadius(platformView, virtualView);
            UpdateVisualProperties(platformView, virtualView);
        }

        private void UpdateVisualProperties(UIButton button, Button view)
        {
            if (button == null || view == null)
                return;

            var layer = button.Layer;
            layer.BorderColor = view.BorderColor.ToCGColor();
            layer.BorderWidth = (nfloat)view.BorderWidth;
            layer.CornerRadius = (nfloat)view.CornerRadius;
            button.BackgroundColor = view.BackgroundColor.ToCGColor();
        }
    }
}

Register the custom handler in your MauiProgram.cs file:

using Microsoft.Maui.Handlers;
using MyMauiApp.Platforms.iOS.Handlers;
using MyMauiApp.Controls;

namespace MyMauiApp
{
    public static class MauiProgram
    {
        public static MauiApp CreateMauiApp()
        {
            var builder = MauiApp.CreateBuilder();
            builder
                .UseMauiApp<App>()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                });

            builder.ConfigureMauiHandlers(handlers =>
            {
                handlers.AddHandler<CustomBorderlessButton, CustomBorderlessButtonHandler>();
            });

            return builder.Build();
        }
    }
}

Step 5: Use the Custom Button in XAML

Finally, use your custom button in XAML as follows: