Translucent and Transparent NavigationBar on iOS

[tj-devel709]

Description of Change

On MAUI iOS, there are some issues with trying to create transparent and translucent UINavigationBars that were possible in Xamarin.Forms. With the changes in this PR, it is now possible to get the super cool styling of a transparent and translucent navbar on NavigationPage, Shell, and FlyoutPage. Because iOS 15 made some changes to the UINavigationBar, there were some differences in the code depending in the iOS version and I will provide screenshots from iOS 11.0 and iOS 17.0.

For the following examples, please note that IgnoreSafeArea="True"is set on the top-level grid in the contentpage.

NavigationPage

When enabling transparency and translucent for the UINavigationBar in a NavigationPage, you'll want to make the NavigationPage's BarBackgroundColor = Colors.Transparent as well as calling yourNavigationPage.On<iOS>().EnableTranslucentNavigationBar() and yourNavigationPage.On<iOS>().SetHideNavigationBarSeparator(true)

NavigationPage Images and Code Sample (click me!)

iOS 17.0	iOS 11.0

MainPage.xaml:

    <ContentPage
        xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
        xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
        x:Class="Maui.Controls.Sample.MainPage"
        xmlns:local="clr-namespace:Maui.Controls.Sample"
        xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls"
        Title="Home"
        >
        <Grid IgnoreSafeArea="True" Background="#333333" RowDefinitions="300,*">
            <BoxView Grid.Row="0" Background="yellow" />
            <Image Source="dotnet_bot.png" />
            <Label Text="Hello, world!" Grid.Row="1"
                    TextColor="White"
                    HorizontalOptions="Center"
                    VerticalOptions="Center" />
        </Grid>
    </ContentPage>

MauiProgram.cs

    class App : Microsoft.Maui.Controls.Application
        {
            protected override Window CreateWindow(IActivationState activationState)
            {
                var navPage = new Microsoft.Maui.Controls.NavigationPage(new MainPage())
                {
                    BarBackgroundColor = Colors.Transparent,
                };
                navPage.On<iOS>().EnableTranslucentNavigationBar();
                navPage.On<iOS>().SetHideNavigationBarSeparator(true);
                return new Window(navPage);
            }
        }

---

FlyoutPage

Similar to the NavigationPage example above, you'll want to make the NavigationPage's BarBackgroundColor = Colors.Transparent as well as calling yourNavigationPage.On<iOS>().EnableTranslucentNavigationBar() and yourNavigationPage.On<iOS>().SetHideNavigationBarSeparator(true). You will then set this navigationPage to the 'Detail' property of the FlyoutPage.

FlyoutPage Images and Code Sample (click me!)

iOS 17.0	iOS 11.0

MainPage.xaml:

    <ContentPage
        xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
        xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
        x:Class="Maui.Controls.Sample.MainPage"
        xmlns:local="clr-namespace:Maui.Controls.Sample"
        xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls"
        Title="Home"
        >
        <Grid IgnoreSafeArea="True" Background="#333333" RowDefinitions="300,*">
            <BoxView Grid.Row="0" Background="yellow" />
            <Image Source="dotnet_bot.png" />
            <Label Text="Hello, world!" Grid.Row="1"
                    TextColor="White"
                    HorizontalOptions="Center"
                    VerticalOptions="Center" />
        </Grid>
    </ContentPage>

SandboxFlyout.cs

using System;
using Microsoft.Maui.Controls;
using Microsoft.Maui.Controls.PlatformConfiguration;
using Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;
using Microsoft.Maui.Graphics;
namespace Maui.Controls.Sample
{
    public partial class SandboxFlyout : Microsoft.Maui.Controls.FlyoutPage
    {
        public SandboxFlyout()
        {
            InitializeComponent();
            var mainPage = new MainPage();
            var navigationPage = new Microsoft.Maui.Controls.NavigationPage(mainPage);
            navigationPage.BarBackgroundColor = Colors.Transparent;
            navigationPage.On<iOS>().SetHideNavigationBarSeparator(true);
            navigationPage.On<iOS>().EnableTranslucentNavigationBar();
            Flyout = new FlyPage();
            Detail = navigationPage;
        }
    }
}

---

Shell

Shell is a little different than the NavigationPage and Flyout Page. Because there is not an existing public property to set for Translucence, if you set Shell.NavBarIsVisible="True" and Shell.BackgroundColor="Transparent", the Shell's navigationBar will now become transparent and translucent.

Shell Images and Code Sample (click me!)

iOS 17.0	iOS 11.0

MainPage.xaml:

<ContentPage
    xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
    xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
    x:Class="Maui.Controls.Sample.MainPage"
    xmlns:local="clr-namespace:Maui.Controls.Sample"
    xmlns:ios="clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls"
    Title="Home"
    Shell.NavBarIsVisible="True"
    Shell.BackgroundColor="Transparent"
    >
    <Grid IgnoreSafeArea="True" Background="#333333" RowDefinitions="300,*">
        <BoxView Grid.Row="0" Background="yellow" />
        <Image Source="dotnet_bot.png" />
        <Label Text="Hello, world!" Grid.Row="1"
                TextColor="White"
                HorizontalOptions="Center"
                VerticalOptions="Center" />
    </Grid>
</ContentPage>

---

Testing

I added a UITest that adds a transparent and translucent UINavigationBar with the NavigationPage inside the Appium UITests below:

UITest
NewSafeAreaNavBariOS.mov

Issues Fixed

Fixes #17022

[AlleSchonWeg]

Hi @tj-devel709,
there are some problems with translucent and safe area : #9053
Will this problems also be adressed?

[tj-devel709]

Hi @tj-devel709, there are some problems with translucent and safe area : #9053 Will this problems also be adressed?

Hello @AlleSchonWeg! I would say that this PR probably does not affect the Large Titles transitions in the issue above but rather being able to have have visible content behind the UINavigationBar.

[AlleSchonWeg]

Okay,
this pull request reminded me of the linked issue. The combination of safe area, translucent, large tiles and LV/CV results in scrolling and snapping issues.

[davidortinau]

Before and after. Looking like what I expect!

[PureWeen]

/rebase

[jsuarezruiz]

Have the snapshots been generated on the server or locally? Must be generated on the CI server.

[tj-devel709]

I generated the screenshots locally and moved them from the snapshot-diff to the snapshot directory. Are they different from the CI?

[Cybrosys]

Is it possible to achieve the same on Android with Shell, the layout doesn't extend in under the NavigationBar during my tests?