Plugin.Maui.BottomSheet 10.0.6

📱 Plugin.Maui.BottomSheet

🚀 Show native BottomSheets with .NET MAUI!

✨ Features

• 🧭 Built-in NavigationService - Seamless navigation between bottom sheets
• 📄 Flexible Content - Open any ContentPage or View as BottomSheet
• 🎨 Customizable Layout - Create BottomSheets in any layout
• 📋 Configurable Header - Full header customization support
• 🏗️ MVVM Support - Complete MVVM pattern integration
• 🎯 Native Performance - Platform-specific implementations for optimal UX

🎯 Quick Demo

Check out the sample project to see the API in action!

🌍 Platform Support

Mobile

<table> <tr> <td>

📱 Apple iOS 15+

<figure> <figcaption>iPhone</figcaption> <img src="screenshots/iOS/Showcase.gif" width="150" height="250" alt="iOS Demo"/> </figure>

<figure> <figcaption>iPad</figcaption> <img src="screenshots/iPad/Showcase.gif" width="200" height="200" alt="iPad Demo"/> </figure>

</td> <td>

🤖 Android API 21+

<figure> <figcaption>Phone</figcaption> <img src="screenshots/Android/Showcase.gif" width="150" height="250" alt="Android Demo"/> </figure>

<figure> <figcaption>Tablet</figcaption> <img src="screenshots/Android/Tablet/Showcase.gif" width="200" height="200" alt="Android Tablet Demo"/> </figure>

</td> </tr> </table>

Desktop

<table> <tr> <td>

💻 MacCatalyst 15+

<img src="screenshots/MacCatalyst/Showcase.gif" height="200" width="500" alt="MacCatalyst Demo"/> </td> <td>

🪟 Windows

<img src="screenshots/MacCatalyst/Showcase.gif" height="200" width="500" alt="Windows Demo"/>

</td> </tr> </table>

🚀 Quick Start

1️⃣ Installation

Install the NuGet package:

dotnet add package Plugin.Maui.BottomSheet

2️⃣ Setup

Enable the plugin in your MauiProgram.cs:

using Plugin.Maui.BottomSheet.Hosting;

var builder = MauiApp.CreateBuilder();
builder
    .UseMauiApp<App>()
    .UseBottomSheet() // 👈 Add this line
    .ConfigureFonts(fonts =>
    {
        fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
        fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
    });

#if DEBUG
builder.Logging.AddDebug();
#endif

return builder.Build();

3️⃣ Basic Usage

Add the XAML namespace:

xmlns:bottomsheet="http://pluginmauibottomsheet.com"

Create a simple bottom sheet:

<bottomsheet:BottomSheet x:Name="MyBottomSheet" IsOpen="{Binding IsSheetOpen}">
    <bottomsheet:BottomSheetContent>
        <Label Text="Hello from Bottom Sheet!" />
    </bottomsheet:BottomSheetContent>
</bottomsheet:BottomSheet>

Set peek height to view height (peek height changes dynamically as view height changes)

<mauibottomsheet:BottomSheet
    PeekHeight="{mauibottomsheet:PeekView View={x:Reference ContentBox}}"
    States="Peek">
    <mauibottomsheet:BottomSheetContent>
        <mauibottomsheet:BottomSheetContent.Content>
            <Grid RowDefinitions="300">
                <BoxView x:Name="ContentBox" Color="Orange" />
            </Grid>
        </mauibottomsheet:BottomSheetContent.Content>
    </mauibottomsheet:BottomSheetContent>
</mauibottomsheet:BottomSheet>

or

<mauibottomsheet:BottomSheet
    PeekHeight="{mauibottomsheet:PeekView ContentBox}"
    States="Peek">
    <mauibottomsheet:BottomSheetContent>
        <mauibottomsheet:BottomSheetContent.ContentTemplate>
            <DataTemplate>
                <Grid RowDefinitions="300">
                    <BoxView x:Name="ContentBox" Color="Orange" />
                </Grid>
            </DataTemplate>
        </mauibottomsheet:BottomSheetContent.ContentTemplate>
    </mauibottomsheet:BottomSheetContent>
</mauibottomsheet:BottomSheet>

📖 API Reference

🔧 Core Properties

Size Modes

🎭 BottomSheet States

🎨 Header Configuration

📱 Content Configuration

🎨 Styling Options

BottomSheet Style Properties

BottomSheet Header Style Properties

🎪 Advanced Examples

📋 Complete XAML Example

<bottomsheet:BottomSheet
    x:Name="AdvancedBottomSheet"
    Padding="20"
    CornerRadius="20"
    HasHandle="True"
    IsCancelable="True"
    IsDraggable="True"
    IsModal="True"
    IsOpen="{Binding IsOpen}"
    ShowHeader="True"
    States="Peek,Medium,Large"
    CurrentState="Medium"
    WindowBackgroundColor="Black">
    
    
    <bottomsheet:BottomSheet.Header>
        <bottomsheet:BottomSheetHeader
            CloseButtonPosition="Right"
            HeaderAppearance="LeftAndRightButton"
            ShowCloseButton="True"
            TitleText="My Awesome Sheet">
            <bottomsheet:BottomSheetHeader.TopLeftButton>
                <Button Command="{Binding LeftButtonCommand}" Text="Cancel" />
            </bottomsheet:BottomSheetHeader.TopLeftButton>
            <bottomsheet:BottomSheetHeader.TopRightButton>
                <Button Command="{Binding RightButtonCommand}" Text="Save" />
            </bottomsheet:BottomSheetHeader.TopRightButton>
        </bottomsheet:BottomSheetHeader>
    </bottomsheet:BottomSheet.Header>
    
    
    <bottomsheet:BottomSheetContent>
        <bottomsheet:BottomSheetContent.ContentTemplate>
            <DataTemplate>
                <VerticalStackLayout>
                    
                    <ContentView>
                        <ContentView.Behaviors>
                            <bottomsheet:BottomSheetPeekBehavior />
                        </ContentView.Behaviors>
                        <Label Text="This content is visible in peek mode" />
                    </ContentView>
                        
                    
                    <Grid>
                        <Label Text="This content appears when expanded" />
                        
                    </Grid>
                </VerticalStackLayout>
            </DataTemplate>
        </bottomsheet:BottomSheetContent.ContentTemplate>
    </bottomsheet:BottomSheetContent>
    
    
    <bottomsheet:BottomSheet.BottomSheetStyle>
        <bottomsheet:BottomSheetStyle>
            <bottomsheet:BottomSheetStyle.HeaderStyle>
                <bottomsheet:BottomSheetHeaderStyle 
                    TitleTextColor="Blue" 
                    TitleTextFontSize="18"
                    TitleTextFontAttributes="Bold"
                    CloseButtonTintColor="Red"/>
            </bottomsheet:BottomSheetStyle.HeaderStyle>
        </bottomsheet:BottomSheetStyle>
    </bottomsheet:BottomSheet.BottomSheetStyle>
</bottomsheet:BottomSheet>

📋 Easy and fast popups with content based size

<mauibottomsheet:BottomSheet
    SizeMode="FitToContent">
    <mauibottomsheet:BottomSheetContent>
        <mauibottomsheet:BottomSheetContent.Content>
            <Grid RowDefinitions="300">
                <BoxView x:Name="ContentBox" Color="Orange" />
            </Grid>
        </mauibottomsheet:BottomSheetContent.Content>
    </mauibottomsheet:BottomSheetContent>
</mauibottomsheet:BottomSheet>

🎨 Global Styling

<Style TargetType="bottomsheet:BottomSheet">
    <Setter Property="BottomSheetStyle">
        <Setter.Value>
            <bottomsheet:BottomSheetStyle>
                <bottomsheet:BottomSheetStyle.HeaderStyle>
                    <bottomsheet:BottomSheetHeaderStyle
                        CloseButtonHeightRequest="40"
                        CloseButtonTintColor="LightBlue"
                        CloseButtonWidthRequest="40"
                        TitleTextColor="Blue"
                        TitleTextFontAttributes="Bold"
                        TitleTextFontAutoScalingEnabled="True"
                        TitleTextFontFamily="OpenSansRegular"
                        TitleTextFontSize="20" />
                </bottomsheet:BottomSheetStyle.HeaderStyle>
            </bottomsheet:BottomSheetStyle>
        </Setter.Value>
    </Setter>
</Style>

🧭 Navigation System

🚀 Setup Navigation

Register your bottom sheets for navigation:

// Basic registration
builder.Services.AddBottomSheet<UserProfilePage>("UserProfile");

// With ViewModel binding
builder.Services.AddBottomSheet<UserProfileSheet, UserProfileViewModel>("UserProfile");

// With default configuration
builder.Services.AddBottomSheet<UserProfilePage>("UserProfile", (sheet, page) =>
{
    sheet.States = [BottomSheetState.Medium, BottomSheetState.Large];
    sheet.CurrentState = BottomSheetState.Large;
    sheet.ShowHeader = true;
    sheet.Header = new BottomSheetHeader()
    {
        TitleText = page.Title,
    };
});

🎯 Using Navigation Service

public class MainViewModel
{
    private readonly IBottomSheetNavigationService _navigationService;

    public MainViewModel(IBottomSheetNavigationService navigationService)
    {
        _navigationService = navigationService;
    }

    // Navigate to a bottom sheet
    public async Task ShowUserProfile()
    {
        await _navigationService.NavigateToAsync("UserProfile");
    }

    // Navigate with parameters
    public async Task ShowUserProfile(int userId)
    {
        var parameters = new BottomSheetNavigationParameters
        {
            { "UserId", userId },
            { "Mode", "Edit" },
            { "ShowActions", true }
        };
        
        await _navigationService.NavigateToAsync("UserProfile", parameters);
    }

    // Navigate with parameters and custom configuration
    public async Task ShowProductDetails(Product product)
    {
        var parameters = new BottomSheetNavigationParameters
        {
            { "Product", product },
            { "Category", product.CategoryId },
            { "ReadOnly", false }
        };

        await _navigationService.NavigateToAsync("ProductDetails", parameters, configure: sheet =>
        {
            sheet.Header.TitleText = product.Name;
            sheet.CurrentState = BottomSheetState.Large;
            sheet.HasHandle = true;
        });
    }

    // Navigate with ViewModel and parameters
    public async Task ShowEditForm<T>(T model, string formType)
    {
        var parameters = new BottomSheetNavigationParameters
        {
            { "Model", model },
            { "FormType", formType },
            { "Timestamp", DateTime.Now }
        };

        await _navigationService.NavigateToAsync<EditFormViewModel>("EditForm", parameters);
    }

    // Navigate with complex object parameters
    public async Task ShowOrderSummary(Order order, List<OrderItem> items, decimal total)
    {
        var parameters = new BottomSheetNavigationParameters
        {
            { "Order", order },
            { "OrderItems", items },
            { "Total", total },
            { "Currency", "USD" },
            { "CanEdit", order.Status == OrderStatus.Draft }
        };

        await _navigationService.NavigateToAsync("OrderSummary", parameters);
    }

    // Go back with result parameters
    public async Task CloseWithResult()
    {
        var resultParameters = new BottomSheetNavigationParameters
        {
            { "Result", "Success" },
            { "ModifiedData", GetModifiedData() },
            { "HasChanges", true }
        };

        await _navigationService.GoBackAsync(resultParameters);
    }

    // Clear all sheets with notification parameters
    public async Task ClearBottomSheetStackAsync()
    {
        var parameters = new BottomSheetNavigationParameters
        {
            { "CloseReason", "ForceClose" },
            { "SaveState", true }
        };

        await _navigationService.ClearBottomSheetStack(parameters);
    }
}

🔄 Navigation Lifecycle

Implement INavigationAware for lifecycle events:

public class UserProfileViewModel : INavigationAware
{
    public void OnNavigatedTo(IBottomSheetNavigationParameters parameters)
    {
        // Sheet opened
        var userId = parameters.GetValue<string>("UserId");
        LoadUserData(userId);
    }

    public void OnNavigatedFrom(IBottomSheetNavigationParameters parameters)
    {
        // Sheet closed or another sheet opened
        SaveChanges();
    }
}

🛡️ Navigation Confirmation

Implement confirmation dialogs:

public class EditUserViewModel : IConfirmNavigationAsync
{
    public async Task<bool> CanNavigateAsync(IBottomSheetNavigationParameters? parameters)
    {
        if (HasUnsavedChanges)
        {
            return await Shell.Current.CurrentPage.DisplayAlert(
                "Unsaved Changes",
                "You have unsaved changes. Do you want to discard them?",
                "Discard",
                "Cancel");
        }
        return true;
    }
}

🎯 Event Handling

📱 Commands

public class MyViewModel
{
    public ICommand TopLeftButtonCommand { get; }
    public ICommand TopRightButtonCommand { get; }
    public ICommand OpeningCommand { get; }
    public ICommand OpenedCommand { get; }
    public ICommand ClosingCommand { get; }
    public ICommand ClosedCommand { get; }
}

🎭 Events

MyBottomSheet.Opening += OnOpening;
MyBottomSheet.Opened += OnOpened;
MyBottomSheet.Closing += OnClosing;
MyBottomSheet.Closed += OnClosed;

🔧 Platform-Specific Features

🤖 Android

🎨 Custom Themes

// Set custom theme before opening
MyBottomSheet.On<Android>().SetTheme(Resource.Style.My_Awesome_BottomSheetDialog);

📏 Size Constraints

// Code approach
MyBottomSheet.On<Android>().SetMaxHeight(800);
MyBottomSheet.On<Android>().SetMaxWidth(600);
MyBottomSheet.On<Android>().SetMargin(new Thickness(10, 0, 10, 0));
MyBottomSheet.On<Android>().SetHalfExpanedRatio = 0.8f;
MyBottomSheet.On<Android>().SetShouldRemoveExpandedCorners = false;

xmlns:androidBottomsheet="http://pluginmauibottomsheet.com/platformconfiguration/android"

<bottomsheet:BottomSheet
    androidBottomsheet:BottomSheet.MaxWidth="300"
    androidBottomsheet:BottomSheet.Margin="10,0,10,0"
    androidBottomsheet:BottomSheet.HalfExpandedRatio="0.8"
    androidBottomsheet:BottomSheet.ShouldRemoveExpandedCorners="false">
    
</bottomsheet:BottomSheet>

🎨 Edge-to-Edge Support

EdgeToEdge support is built-in and enabled by default. If you create your own theme make sure to derive from ThemeOverlay.MaterialComponents.BottomSheetDialog and that navigationBarColor is translucent.

To disable:

<item name="enableEdgeToEdge">false</item>

💻 MacCatalyst

By design, sheets are always modal on macOS.

🪟 Windows

To ensure the same user experience (UX) across desktop applications, Windows sheets are always modal too. The sheet implementation mimics Microsoft.UI.Xaml.Controls.ContentDialog therefore some default properties are set.

📏 Size Constraints

// Code approach
MyBottomSheet.On<Windows>().SetMaxHeight(800);
MyBottomSheet.On<Windows>().SetMaxWidth(600);
MyBottomSheet.On<Windows>().SetMinHeight(800);
MyBottomSheet.On<Windows>().SetMinWidth(600);

xmlns:windowsBottomsheet="http://pluginmauibottomsheet.com/platformconfiguration/windows"

<bottomsheet:BottomSheet
    androidBottomsheet:BottomSheet.MinWidth="300"
    androidBottomsheet:BottomSheet.MinHeight="300"
    androidBottomsheet:BottomSheet.MaxWidth="300"
    androidBottomsheet:BottomSheet.MaxHeight="300">
    
</bottomsheet:BottomSheet>

📱 Platform Considerations

🔄 Lifecycle Events

📱 Platform Lifecycle Integration

using Microsoft.Maui.LifecycleEvents;
using Plugin.Maui.BottomSheet.LifecycleEvents;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .UseBottomSheet();
        
        #if ANDROID
        builder.ConfigureLifecycleEvents(events =>
        {
            events.AddAndroid(android =>
            {
                android.OnBottomSheetBackPressed(activity =>
                {
                    // Handle back button press
                    Debug.WriteLine("BottomSheet back button pressed");
                });
            });
        });
        #endif

        return builder.Build();
    }
}

🚨 Important Notes & Best Practices

🎯 Performance Tips

• Use ContentTemplate instead of Content for better performance
• Implement lazy loading for complex content
• Consider using INavigationAware for proper lifecycle management

🔄 Navigation Best Practices

• Don't mix IsOpen with navigation methods
• Always implement IConfirmNavigation for forms with user input

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• 🐛 Bug Reports
• 💬 Discussions

<div> <b>Made with ❤️ for the .NET MAUI community</b> </div>