Plugin.Maui.CustomTabbedPage 1.0.1

Plugin.Maui.CustomTabbedPage

A lightweight yet flexible tab control for .NET MAUI that lets you host real ContentPage children while fully customising the native tab bar on iOS and Android. Control per-tab icons, badges, and text visibility, as well as global bar colours, opacity, and iOS appearance mode — all from XAML or C#.

Supported Platforms

Installation

Install from NuGet:

dotnet add package Plugin.Maui.CustomTabbedPage

Or search for Plugin.Maui.CustomTabbedPage in the NuGet package manager inside Visual Studio / Rider.

Getting Started

1. Register the plugin

In MauiProgram.cs, call UseCustomTabbedPage() to register the native mappers:

using Plugin.Maui.CustomTabbedPage.Extensions;

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();

    builder
        .UseMauiApp<App>()
        .UseCustomTabbedPage();

    return builder.Build();
}

2. Create your tab pages

Each tab must derive from CustomTabPage instead of ContentPage:

using Plugin.Maui.CustomTabbedPage.Controls;

public partial class HomePage : CustomTabPage
{
    public HomePage() => InitializeComponent();
}

Or in XAML:

<controls:CustomTabPage
    xmlns:controls="clr-namespace:Plugin.Maui.CustomTabbedPage.Controls;assembly=Plugin.Maui.CustomTabbedPage"
    x:Class="MyApp.Views.HomePage"
    Title="Home">
    
</controls:CustomTabPage>

3. Build your tabbed shell

Use CustomTabbedPage as your root page and add CustomTabPage children:

<controls:CustomTabbedPage
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:controls="clr-namespace:Plugin.Maui.CustomTabbedPage.Controls;assembly=Plugin.Maui.CustomTabbedPage"
    xmlns:views="clr-namespace:MyApp.Views"
    x:Class="MyApp.MainTabbedPage"
    TabBarSelectedColor="#512BD4"
    TabBarUnselectedColor="#9E9E9E"
    TabBarBackgroundColor="#FFFFFF"
    TabBarBackgroundOpacity="1.0"
    RemoveTopShadowLine="True"
    ShowSelectedTabUnderline="True"
    TabBarIndicatorColor="#512BD4"
    iOSMode="Branded">

    <views:HomePage
        Title="Home"
        ShowText="True"
        BadgeIsVisible="False" />

    <views:NotificationsPage
        Title="Alerts"
        ShowText="True"
        BadgeIsVisible="True"
        BadgeText="3"
        TabBadgeColor="#FF3B30"
        TabBadgeTextColor="White" />

    <views:ProfilePage
        Title="Profile"
        ShowText="True" />

</controls:CustomTabbedPage>

Set App.MainPage to an instance of your tabbed page:

public partial class App : Application
{
    public App() => MainPage = new MainTabbedPage();
}

API Reference

CustomTabbedPage

The top-level container. Inherits from TabbedPage.

Tab bar appearance

Methods

CustomTabPage

The base class for individual tab pages. Inherits from ContentPage.

Per-tab properties

iOSTabBarMode enum

Advanced Usage

Dynamic badges

Update BadgeText and BadgeIsVisible at any time — the tab bar refreshes automatically via property-change callbacks:

// Show a badge with count
myAlertsTab.BadgeText = unreadCount.ToString();
myAlertsTab.BadgeIsVisible = unreadCount > 0;

Per-tab selected / unselected icons

<views:HomePage
    Title="Home"
    SelectedIcon="home_selected.png"
    UnselectedIcon="home_outline.png" />

Hiding tab titles (icon-only tabs)

<views:HomePage Title="Home" ShowText="False" />

Selected tab underline indicator

Show a coloured line beneath the active tab. If TabBarIndicatorColor is Transparent (the default) the line takes the value of TabBarSelectedColor:

<controls:CustomTabbedPage
    ShowSelectedTabUnderline="True"
    TabBarIndicatorColor="#C9A843"
    TabBarSelectedColor="#C9A843"
    ...>

NativeGlass mode (iOS 18+)

Use iOSMode="NativeGlass" to adopt the system's translucent Liquid Glass look. In this mode the colour customisation properties have no effect.

<controls:CustomTabbedPage iOSMode="NativeGlass" ...>

Building from Source

1. Clone the repository.
2. Install the .NET 9 SDK and MAUI workload:

   dotnet workload install maui
   

3. Open Plugin.Maui.CustomTabbedPage.sln or build from the command line:

   dotnet build src/Plugin.Maui.CustomTabbedPage
   

4. Run the unit tests (no device required):

   dotnet test tests/Plugin.Maui.CustomTabbedPage.Tests
   

5. Run the sample app from Visual Studio / Rider, targeting an iOS simulator or Android emulator.

Known Limitations

• MacCatalyst and Windows are not yet supported — CustomTabbedPage will fall back to the default MAUI TabbedPage behaviour on those platforms.
• Advanced layouts such as floating action buttons, animated tab indicators, or fully bespoke tab bar views are outside the scope of this library but can be built on top of the architecture provided.
• iOSMode="NativeGlass" requires iOS 18 or later; on earlier versions it falls back to the system default appearance.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md and CODE_OF_CONDUCT.md before opening a pull request.

Changelog

See CHANGELOG.md for a full list of changes.

License

This project is licensed under the MIT License. See LICENSE for details.