The49.Maui.BottomSheet 1.0.0-alpha5

NOTE: Coming from Gerald Versluis' video? Make sure to check the section on what changed since the video was made

What is Maui.BottomSheet?

Setup

Enable this plugin by calling UseBottomSheet() in your MauiProgram.cs

using Maui.Insets;

public static class MauiProgram
{
	public static MauiApp CreateMauiApp()
	{
		var builder = MauiApp.CreateBuilder();
		
		// Initialise the plugin
		builder
                    .UseMauiApp<App>()
                    .UseBottomSheet();

		// the rest of your logic...
	}
}

XAML usage

In order to make use of the plugin within XAML you can use this namespace:

xmlns:the49="https://schemas.the49.com/dotnet/2023/maui"

Quick usage

Simply create a ContentPage. Replace the extended class with BottomSheetPage in code-behind and in XAML:

using The49.Maui.BottomSheet;

public class MySheetPage : BottomSheetPage
{
    public MySheetPage()
    {
        InitializeComponent();
    }
}

<the49:BottomSheet xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:the49="https://schemas.the49.com/dotnet/2023/maui"
             x:Class="MyApp.MySheetPage"
             Title="MySheetPage">
            
</the49:BottomSheet>

The sheet can be opened by calling the Show(Window) method of the page. It can be closed using Dismiss():

const page = new MySheetPage();

// Pass the window in which the sheet should show. Usually accessible from any other page of the app.
page.Show(Window);

// Call to programatically close the sheet
page.Dismiss();

On Android, make sure your application's theme extends the Material3 theme. This mean you need a Platforms/Android/Resources/values/styles.xml file with the following content:

<?xml version="1.0" encoding="utf-8" ?>
<resources>
	<style name="Maui.MainTheme" parent="Theme.Material3.DayNight"></style>
</resources>

If you already have this file, just make sure the Maui.MainTheme style inherits the Theme.Material3.DayNight parent.

API

This library offers a BottomSheetPage, an extension of the ContentPage with extra functionality

Properties

The following properties are available to use:

* iOS doesn't support the property largestUndimmedDetentIdentifier for custom detents as of right now. See iOS documentation

Detents:

Detents are snap point at which the sheet will stop when a drag gesture is released See iOS definition.

On Android only 3 detents are supported (See implemenation section for more info).

On iOS, detents are only fully supported for iOS 16 and up. On iOS 15, medium and large detents are used instead See iOS documentation.

Available detents

Example:

<the49:BottomSheetPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:the49="https://schemas.the49.com/dotnet/2023/maui"
             x:Class="MyApp.SheetPage"
             Title="SheetPage">
    <the49:BottomSheetPage.Detents>
        <the49:DetentsCollection>
            
            <the49:FullscreenDetent />
            
            <the49:ContentDetent />
            
            <the49:HeightDetent Height="120" />
            
            <the49:RatioDetent Height="0.45" />
            
            <the49:AnchorDetent Anchor="{x:Reference divider}" />
        </the49:DetentsCollection>
    </the49:BottomSheetPage.Detents>
    <VerticalStackLayout Spacing="16">
        <VerticalStackLayout>
            
        </VerticalStackLayout>
        <BoxView x:Name="divider" />
        <VerticalStackLayout>
            
        </VerticalStackLayout>
    </VerticalStackLayout>
</the49:BottomSheetPage>

Custom detent

You can create a custom detent by extending the default Detent class and implementing its GetHeight abstract method

Events

The following events are available to use:

Platform specifics

On Android, the Google.Android.Material.BottomSheet.BottomSheetBehavior is made available under sheet.Controller.Behavior, to ensure the property is set, access it when the Showing event is fired. Learn more about it here: BottomSheetBehavior  |  Android Developers

On iOS, the UIKit.UISheetPresentationController is made available under sheet.Controller.SheetPresentationController, to ensure the property is set, access it when the Showing event is fired. Learn more about it here: UISheetPresentationController | Apple Developer Documentation

Common questions

How do I prevent the rounded corner to animate on Android?

var sheet = new MySheet();
sheet.Showing += (s, e) =>
{
    page.Controller.Behavior.DisableShapeAnimations();
};
sheet.Show(Window);

How do I change the corner radius?

This will be different on Android and iOS as they each provide their own design implementation

On iOS

var sheet = new MySheet();
sheet.Showing += (s, e) =>
{
    sheet.Controller.SheetPresentationController.PreferredCornerRadius = 2;
};
sheet.Show(Window);

On Android (Using Android styles). In your Platforms/Android/Resources/values/themes.xml (or equivalent) add the following styles

<style name="ThemeOverlay.App.BottomSheetDialog" parent="ThemeOverlay.Material3.BottomSheetDialog">
    <item name="bottomSheetStyle">@style/ModalBottomSheetDialog</item>
</style>

<style name="ModalBottomSheetDialog" parent="Widget.Material3.BottomSheet.Modal">
    <item name="shapeAppearance">@style/ShapeAppearance.App.LargeComponent</item>
</style>

<style name="ShapeAppearance.App.LargeComponent" parent="ShapeAppearance.Material3.LargeComponent">
    <item name="cornerFamily">rounded</item>
    <item name="cornerSize">2dp</item>
</style>

And in your <style name="Maui.MainTheme" ...> add the following item:

<item name="bottomSheetDialogTheme">@style/ThemeOverlay.App.BottomSheetDialog</item>

Implementation details

iOS

The bottom sheet on iOS is presented using the UIViewController's PresentViewController and configuring the sheet with UISheetPresentationController.

Detents are created using the custom method

Android

The Material library's bottom sheet is used.

Standard sheets attach a CoordinatorLayout to the navigation view and insert a FrameLayout with the com.google.android.material.bottomsheet.BottomSheetBehavior Behavior.

Modal sheets use a BottomSheetDialogFragment

Detents are created using a combination of expandedOffset, halfExpandedRatio and peekHeight. These are the only configurable stop points for the bottom sheets, and that is why this library only supports up to 3 detents on Android.

Changes since Gerald Versluis' video

If you're coming from Gerald Versluis' video, a few things have changed. Here is what you need to know:

• Property names have been updated to be more consistent, discoverable and aligned with standard MAUI properties:
  • ShowHandle is now HasHandle
  • Cancelable is now IsCancelable
  • IsModal is now HasBackdrop
• Detents in XAML must be specified within a DetentsCollection

Made within The49