Handlers

.NET Multi-platform App UI (.NET MAUI) provides a collection of cross-platform controls that can be used to display data, initiate actions, indicate activity, display collections, pick data, and more. Each control has an interface representation that abstracts the control. Cross-platform controls that implement these interfaces are known as virtual views. Handlers map these virtual views to controls on each platform, which are known as native views. Handlers are also responsible for instantiating the underlying native view, and mapping the cross-platform control API to the native view API. For example, on iOS a handler maps a .NET MAUI Button to an iOS UIButton. On Android, the Button is mapped to an AppCompatButton:

.NET MAUI handlers are accessed through their control-specific interface, such as IButton for a Button. This avoids the cross-platform control having to reference its handler, and the handler having to reference the cross-platform control.

Each handler class exposes the native view for the cross-platform control via its PlatformView property. This property can be accessed to set native view properties, invoke native view methods, and subscribe to native view events. In addition, the cross-platform control implemented by the handler is exposed via its VirtualView property.

When you create a cross-platform control whose implementation is provided on each platform by native views, you should implement a handler that maps the cross-platform control API to the native view APIs. For more information, see Create custom controls with handlers.

You can also customize handlers to augment the appearance and behavior of existing cross-platform controls beyond the customization that's possible through the control's API. This handler customization modifies the native views for the cross-platform control. Handlers are global, and customizing a handler for a control will result in all controls of the same type being customized in your app. For more information, see Customize .NET MAUI controls with handlers.

Mappers

A key concept of .NET MAUI handlers is mappers. Each handler typically provides a property mapper, and sometimes a command mapper, that maps the cross-platform control's API to the native view's API.

A property mapper defines what Actions to take when a property change occurs in the cross-platform control. It's a Dictionary that maps the cross-platform control's properties to their associated Actions. Each platform handler then provides implementations of the Actions, which manipulate the native view API. This ensures that when a property is set on a cross-platform control, the underlying native view is updated as required.

A command mapper defines what Actions to take when the cross-platform control sends commands to native views. They're similar to property mappers, but allow for additional data to be passed. A command in this context doesn't mean an ICommand implementation. Instead, a command is just an instruction, and optionally its data, that's sent to a native view. The command mapper is a Dictionary that maps the cross-platform control's command to their associated Actions. Each handler then provides implementations of the Actions, which manipulate the native view API. This ensures that when a cross-platform control sends a command to its native view, the native view is updated as required. For example, when a ScrollView is scrolled, the ScrollViewHandler uses a command mapper to invoke an Action that accepts a scroll position argument. The Action then instructs the underlying native view to scroll to that position.

The advantage of using mappers to update native views is that native views can be decoupled from cross-platform controls. This removes the need for native views to subscribe to and unsubscribe from cross-platform control events. It also allows for easy customization because mappers can be modified without subclassing.

Handler lifecycle

All handler-based .NET MAUI controls support two handler lifecycle events:

• HandlerChanging is raised when a new handler is about to be created for a cross-platform control, and when an existing handler is about to be removed from a cross-platform control. The HandlerChangingEventArgs object that accompanies this event has NewHandler and OldHandler properties, of type IElementHandler. When the NewHandler property isn't null, the event indicates that a new handler is about to be created for a cross-platform control. When the OldHandler property isn't null, the event indicates that the existing native control is about be removed from the cross-platform control, and therefore any native events should be unwired and other cleanup performed.
• HandlerChanged is raised after the handler for a cross-platform control has been created. This event indicates that the native control that implements the cross-platform control is available, and all the property values set on the cross-platform control have been applied to the native control.

Note

The HandlerChanging event is raised on a cross-platform control before the HandlerChanged event.

In addition to these events, each cross-platform control also has an overridable OnHandlerChanging method that's invoked when the HandlerChanging event is raised, and a OnHandlerChanged method that's invoked when the HandlerChanged event is raised.

View handlers

The following table lists the types that implement views in .NET MAUI:

View	Interface	Handler	Property Mapper	Command Mapper
ActivityIndicator	IActivityIndicator	ActivityIndicatorHandler	Mapper	CommandMapper
BlazorWebView	IBlazorWebView	BlazorWebViewHandler	BlazorWebViewMapper
Border	IBorderView	BorderHandler	Mapper	CommandMapper
BoxView	IShapeView, IShape	ShapeViewHandler	Mapper	CommandMapper
Button	IButton	ButtonHandler	ImageButtonMapper, TextButtonMapper, Mapper	CommandMapper
CarouselView		CarouselViewHandler	Mapper
Cell		CellRenderer	Mapper	CommandMapper
CheckBox	ICheckBox	CheckBoxHandler	Mapper	CommandMapper
CollectionView		CollectionViewHandler	<Mapper
ContentView	IContentView	ContentViewHandler	Mapper	CommandMapper
DatePicker	IDatePicker	DatePickerHandler	Mapper	CommandMapper
Editor	IEditor	EditorHandler	Mapper	CommandMapper
Ellipse	IShape	ShapeViewHandler	Mapper	CommandMapper
Entry	IEntry	EntryHandler	Mapper	CommandMapper
EntryCell		EntryCellRenderer	Mapper	CommandMapper
Frame		FrameRenderer	Mapper	CommandMapper
GraphicsView	IGraphicsView	GraphicsViewHandler	Mapper	CommandMapper
Image	IImage	ImageHandler	Mapper	CommandMapper
ImageButton	IImageButton	ImageButtonHandler	ImageMapper, Mapper
ImageCell		ImageCellRenderer	Mapper	CommandMapper
IndicatorView	IIndicatorView	IndicatorViewHandler	Mapper	CommandMapper
Label	ILabel	LabelHandler	Mapper	CommandMapper
Line	IShape	LineHandler	Mapper	CommandMapper
ListView		ListViewRenderer	Mapper	CommandMapper
Map	IMap	MapHandler	Mapper	CommandMapper
Path	IShape	PathHandler	Mapper	CommandMapper
Picker	IPicker	PickerHandler	Mapper	CommandMapper
Polygon	IShape	PolygonHandler	Mapper	CommandMapper
Polyline	IShape	PolylineHandler	Mapper	CommandMapper
ProgressBar	IProgress	ProgressBarHandler	Mapper	CommandMapper
RadioButton	IRadioButton	RadioButtonHandler	Mapper	CommandMapper
Rectangle	IShape	RectangleHandler	Mapper	CommandMapper
RefreshView	IRefreshView	RefreshViewHandler	Mapper	CommandMapper
RoundRectangle	IShape	RoundRectangleHandler	Mapper	CommandMapper
ScrollView	IScrollView	ScrollViewHandler	Mapper	CommandMapper
SearchBar	ISearchBar	SearchBarHandler	Mapper	CommandMapper
Slider	ISlider	SliderHandler	Mapper	CommandMapper
Stepper	IStepper	StepperHandler	Mapper	CommandMapper
SwipeView	ISwipeView	SwipeViewHandler	Mapper	CommandMapper
Switch	ISwitch	SwitchHandler	Mapper	CommandMapper
SwitchCell		SwitchCellRenderer	Mapper	CommandMapper
TableView		TableViewRenderer	Mapper	CommandMapper
TextCell		TextCellRenderer	Mapper	CommandMapper
TimePicker	ITimePicker	TimePickerHandler	Mapper	CommandMapper
ViewCell		ViewCellRenderer	Mapper	CommandMapper
WebView	IWebView	WebViewHandler	Mapper	CommandMapper

Page handlers

The following table lists the types that implement pages in .NET MAUI:

Page	Android Handler	iOS/Mac Catalyst Handler	Windows Handler	Property Mapper	Command Mapper
ContentPage	PageHandler	PageHandler	PageHandler	Mapper	CommandMapper
FlyoutPage	FlyoutViewHandler	PhoneFlyoutPageRenderer	FlyoutViewHandler	Mapper	CommandMapper
NavigationPage	NavigationViewHandler	NavigationRenderer	NavigationViewHandler	Mapper	CommandMapper
TabbedPage	TabbedViewHandler	TabbedRenderer	TabbedViewHandler	Mapper	CommandMapper
Shell	ShellHandler	ShellRenderer	ShellRenderer	Mapper	CommandMapper