Edit

StatusBarBehavior

  • Article

The StatusBarBehavior provides the ability to customize the color and style of a devices status bar.

The StatusBarBehavior applies the color and style values when the properties are updated. The values are also applied based on the ApplyOn property, this property makes it possible to define which lifecycle event is used:

  • StatusBarApplyOn.OnBehaviorAttachedTo - Applies the color and style when the behavior has been attached to a page. This is the default.
  • StatusBarApplyOn.OnPageNavigatedTo - Applies the color and style when the page has been navigated to.

Note

If your application changes the status bar appearance on a per page basis then you should make use of the StatusBarApplyOn.OnPageNavigatedTo value for the ApplyOn property. Otherwise when navigating back the system will preserve the status bar appearance from the page the user navigated from and not to.

Important

The .NET MAUI Community Toolkit Behaviors do not set the BindingContext of a behavior, because behaviors can be shared and applied to multiple controls through styles. For more information refer to .NET MAUI Behaviors

Syntax

XAML

Including the XAML namespace

In order to use the toolkit in XAML the following xmlns needs to be added into your page or view:

xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"

Therefore the following:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml">

</ContentPage>

Would be modified to include the xmlns as follows:

<ContentPage
    x:Class="CommunityToolkit.Maui.Sample.Pages.MyPage"
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit">

</ContentPage>

Using the StatusBarBehavior

The StatusBarBehavior can be used as follows in XAML:

<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
             xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
             xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
             x:Class="MyLittleApp.MainPage">
    
    <ContentPage.Behaviors>
        <toolkit:StatusBarBehavior StatusBarColor="Fuchsia" StatusBarStyle="LightContent" />
    </ContentPage.Behaviors>

</ContentPage>

C#

The StatusBarBehavior can be used as follows in C#:

class MyPage : ContentPage
{
    public MyPage()
    {
        this.Behaviors.Add(new StatusBarBehavior
        {
            StatusBarColor = Colors.Red,
            StatusBarStyle = StatusBarStyle.LightContent
        });
    }
}

There's another way to access the Statusbar APIs on C#, you can call the methods directly, as you can see in the snippet below:

class MyPage : ContentPage
{
    protected override void OnNavigatedTo(NavigatedToEventArgs args)
    {
        base.OnNavigatedTo(args);
        CommunityToolkit.Maui.Core.Platform.StatusBar.SetColor(statusBarColor);
        CommunityToolkit.Maui.Core.Platform.StatusBar.SetStyle(StatusBarStyle.LightContent);
    }
}

Warning

If you want to add this code the MainPage's constructor, OnAppearing or OnNavigatedTo methods, please use the Behavior instead. Using directly on these places can crash your application since the platform-specific components may not be initialized.

Configuration

No changes needed.

Properties

Property Type Description
ApplyOn StatusBarBehavior When to apply the status bar color and style.
StatusBarColor Color The Color name from the Microsoft.Maui.Graphics namespace.
StatusBarStyle StatusBarStyle The style used by statusbar, can be LightContent, DarkContent or Default.

Examples

You can find an example of this behavior in action in the .NET MAUI Community Toolkit Sample Application.

API

You can find the source code for StatusBarBehavior over on the .NET MAUI Community Toolkit GitHub repository.