TitleBar Functional Spec

Control category: Basic Input

Background

Motivations for the TitleBar control include:

• Achieve parity with Fluent Windows Visual Design Library.
• Bridge the gap between Shell / Win32 title bar and a fully custom Xaml titlebar.
• Simplify the developer experience for implementing the modern title bar.

Description

The title bar is a fundamental component of a Windows app’s user interface. Here are its key features and functionalities:

1. Display Information:
   • The title bar prominently displays the name of the app or document currently open. Users can quickly identify which app they are interacting with.
   • Additionally, the title bar may include other relevant information, such as the document title or the current state (e.g., “Editing,” “Viewing,” etc.).
2. Window Controls:
   • Minimize Button: Clicking the minimize button (usually represented by an underscore icon) reduces the app window to the taskbar or system tray.
   • Maximize Button: Clicking the maximize button (usually represented by a square icon) expands the app window to fill the screen.
   • Close Button: Clicking the close button (usually represented by an “X” icon) closes the app window.
3. Drag and Move:
   • Users can click and drag the title bar to move the app window around the screen. This allows them to position the window wherever they prefer.
4. Theming and Integration:
   • The title bar can be customized to match the app’s visual style using Mica theming.
   • It also integrates with other WinUI controls, such as NavigationView, AutoSuggestBox, and PersonPicture, providing a cohesive user experience.

Is this the right control?

A title bar is a core component of a Windows app, and the shell version of the title bar is shipped with the basic WinUI app template by default.

Use the WinUI TitleBar when you want further customizations such as subtitles, Mica theming, and integrations with WinUI Controls.

Note: WinUI TitleBar does not handle Caption Buttons - it simply allocates space where the caption buttons appear, depending on RTL or LTR settings. Caption Buttons and its customizations are handled by the AppWindow TitleBar.

Sample scenarios

#Scenario: Default TitleBar

XAML

1<Window
2    x:Class="App1.MainWindow"
3    xmlns:local="using:App1"
4    mc:Ignorable="d">
5
6    <Grid>
7        <Grid.RowDefinitions>
8            <RowDefinition Height="Auto" /> <!-- Title Bar -->
9            <RowDefinition Height="*" /> <!-- App Content -->
10        </Grid.RowDefinitions>
11        <TitleBar x:Name="DefaultTitleBar" Title="Default TitleBar" Subtitle="Preview">
12            <TitleBar.IconSource>
13                <SymbolIconSource Symbol="Home"/>
14            </TitleBar.IconSource>
15        </TitleBar>
16
17        <!-- App content -->
18    </Grid>
19</Window>

C#

1public MainWindow()
2{
3    this.InitializeComponent();
4
5    // C# code to set AppTitleBar UIElement as Titlebar
6    Window window = this; 
7    window.ExtendsContentIntoTitleBar = true;  // Hides the default system titlebar.
8    window.SetTitleBar(this.DefaultTitleBar); // Replace system titlebar with the WinUI Titlebar.
9    
10    // Note: If not title bar is specified, the default system titlebar will be rendered, regardles of the ExtendsContentIntoTitleBar property.
11} 

Note: TitleBar currently needs to be set explicitly in the grid.row and referenced by Window in codebehind as shown above. Improvements to Window are being considered to avoid this extra grid layout and codebehind. Please see Appendix of Functional Spec.

#Scenario: TitleBar with WinUI Controls Integration

TitleBar with common WinUI Controls: AutoSuggestBox, PersonPicture, AppBarButton.

XAML

1<TitleBar 
2    x:Name="ControlsTitleBar" 
3    Title="ControlsTitleBar" 
4    Subtitle="Preview" 
5    Background="Transparent" 
6    IsBackButtonVisible="True"
7    IsPaneToggleButtonVisible="True">
8    <TitleBar.IconSource>
9        <SymbolIconSource Symbol="Home"/>
10    </TitleBar.IconSource>
11    <TitleBar.Content>
12        <AutoSuggestBox PlaceholderText="Search" QueryIcon="Find" />
13    <TitleBar.Content>
14    <TitleBar.ContentAfter>
15        <StackPanel Orientation="Horizontal">
16            <AppBarButton Icon="More" Label="MoreSymbolIcon" />
17            <PersonPicture DisplayName="Jane Doe" />
18        </StackPanel>
19    </TitleBar.ContentAfter>
20</TitleBar>

#Scenario: TitleBar with NavigationView L-Pattern Integration

Titlebar and NavigationView in an L-Pattern.

TitleBar and NavigationView is in Minimal DisplayMode. Note that TitleBar IconSource is collapsed in minimal mode.

XAML

1<Grid>
2    <Grid.RowDefinitions>
3        <RowDefinition Height="Auto" />
4        <RowDefinition Height="*" />
5    </Grid.RowDefinitions>
6    <TitleBar 
7        x:Name="NavViewTitleBar" 
8        Title="NavView TitleBar"
9        Background="Transparent" 
10        IsBackButtonVisible="True"
11        IsBackButtonEnabled="{x:Bind NavFrame.CanGoBack}"
12        BackRequested="NavViewTitleBar_BackRequested"
13        PaneToggleRequested="NavViewTitleBar_PaneToggleRequested">
14        <TitleBar.IconSource>
15            <SymbolIconSource Symbol="Home"/>
16        </TitleBar.IconSource>
17    </TitleBar>
18
19    <NavigationView
20        x:Name="NavView"
21        Grid.Column="1">
22
23        <!-- TitleBar with NavigationView L-Pattern Overwriting resources -->
24        <NavigationView.Resources>
25            <!-- This is the border between NavView and NavView Content -->
26            <Thickness x:Key="NavigationViewContentGridBorderThickness">1,1,0,0</Thickness>
27            <!-- This is the rounded corner on the Top left of the L Pattern -->
28            <CornerRadius x:Key="NavigationViewContentGridCornerRadius">8,0,0,0</CornerRadius>
29        </NavigationView.Resources>
30
31        <Frame x:Name="NavFrame" />
32
33        <NavigationView.MenuItems>
34            ...
35        </NavigationView.Menuitems>
36    </NavigationView>
37</Grid>

Note: Should the NavView resources be the default to avoid needing the extra code? This will be a question of what pattern will be shipped in WinUI Templates by default.

C#

1public MainWindow()
2{
3    this.InitializeComponent();
4
5    Window window = this; 
6    window.ExtendsContentIntoTitleBar = true;
7    window.SetTitleBar(this.DefaultTitleBar);
8}
9
10private void NavViewTitleBar_BackRequested(TitleBar sender, object args)
11{
12    if (NavFrame.CanGoBack)
13    {
14        NavFrame.GoBack();
15    }
16}
17
18private void NavViewTitleBar_PaneToggleRequested(TitleBar sender, object args)
19{
20    NavView.IsPaneOpen = !NavView.IsPaneOpen;
21}

Note: How can we avoid this extra code-behind?

API Pages

#TitleBar class

Represents a control that provides the title and system buttons for a window or application. It typically appears at the top of the window and includes core functionalities such as drag, minimize, maximize, and close buttons.

Namespace: Microsoft.UI.Xaml.Controls

1public class TitleBar : Control

#TitleBar.ContentBefore property

Gets and sets elements within the TitleBar's ContentBefore column.

1public UIElement ContentBefore { get; set; }

#Property Value

Represents the ContentBefore content property of the TitleBar control which can be populated in both XAML markup and code. The default is null.

#Remarks

The content property of ContentBefore can only be set once. Elements are left aligned by default.

If IsBackButtonVisible or IsPaneToggleButtonVisisble is true, custom content set in the ContentBefore property will automatically be appended to the ContentBefore column in TitleBar layout.

If the property is not null, TitleBar automatically configures its height to TitleBarExpandedHeight in codebehind. See ThemeResources section for further details.

#TitleBar.Title property

Gets or sets the Title text to be displayed on the TitleBar.

1public String Title { get; set; }

#Property Value

Represents the title string to be displayed on the TitleBar. The default is null.

#Remarks

If TitleBar is in minimal display mode, Title textbox will automatically be collapsed. If Title string is empty, Title textbox will be collapsed.

#TitleBar.Subtitle property

Gets or sets the Subtitle text to be displayed on the TitleBar. This is generally used for versioning, such as "Preview", "Beta", etc.

1public String Subtitle { get; set; }

#Property Value

Represents the subtitle string to be displayed on the TitleBar. The default is null.

#Remarks

If TitleBar is in minimal display mode, Subtitle textbox will automatically be collapsed. If Subtitle string is empty, Subtitle textbox will be collapsed.

#TitleBar.IconSource property

Gets or sets the TitleBar's icon.

1public IconSource IconSource { get; set; }

#Property Value

Represents the icon associated with the TitleBar. The default is null.

#TitleBar.Content property

Gets and sets elements within the TitleBar's Content column.

1public UIElement Content { get; set; }

#Property Value

Represents the Content property of the TitleBar control which can be populated in both XAML markup and code.

This is typically used to populate controls such as AutoSuggestBox. The default is null.

#Remarks

The content property of Content can only be set once. Elements are center aligned by default.

If the property is not null, TitleBar automatically configures its height to TitleBarExpandedHeight in codebehind. See ThemeResources section for further details.

#TitleBar.ContentAfter property

Gets and sets elements within the TitleBar's ContentAfter column.

1public UIElement ContentAfter { get; set; }

#Property Value

Represents the ContentAfter property of the TitleBar control which can be populated in both XAML markup and code.

This is typically used to populate controls such as PersonPicture and the "More" AppBarButton. The default is null.

#Remarks

The content property of ContentAfter can only be set once. Elements are right aligned by default.

If the property is not null, TitleBar automatically configures its height to TitleBarExpandedHeight in codebehind. See ThemeResources section for further details.

#TitleBar.IsBackButtonVisible property

Gets and sets TitleBar's BackButton visiblity.

1public Boolean IsBackButtonVisible { get; set; }

#Property Value

Represents the visiblity of TitleBar's BackButton. The default is false.

#TitleBar.IsBackButtonEnabled property

Gets and sets BackButton's IsEnabled property.

1public Boolean IsBackButtonEnabled { get; set; }

#Property Value

Represents the IsEnabled property of TitleBar's BackButton. The default is true.

#Remarks

This property is typically bound to an accompanying NavFrame's CanGoBack property: IsBackButtonEnabled="{x:Bind NavFrame.CanGoBack}"

#TitleBar.IsPaneToggleButtonVisible property

Gets and sets TitleBar's PaneToggleButton visiblity.

1public Boolean IsPaneToggleButtonVisible { get; set; }

#Property Value

Represents the visiblity of TitleBar's PaneToggleButton. The default is false.

#Remarks

TitleBar's PaneToggleButton is only used with NavigationView and when NavigationView is in Minimal DisplayMode. In other display mode scenarios, the PaneToggleButton is owned and handled by NavigationView.

#TitleBar.BackRequested event

Occurs whenever BackButton is clicked.

C#

1public event TypedEventHandler<TitleBar, Object> BackRequested;

#Remark

This event is raised when internal BackButton raises a Click event.

#TitleBar.PaneToggleRequested event

Occurs whenever PaneToggleButton is clicked.

C#

1public event TypedEventHandler<TitleBar, Object> PaneToggleRequested;

#Remark

This event is raised when internal PaneToggleButton raises a Click event.

#TitleBarTemplateSettings Class

#TitleBarAutomationPeer Class

Exposes TitleBar types to Microsoft UI Automation.

Namespace: Microsoft.UI.Xaml.Automation.Peers

1public class TitleBarAutomationPeer :  Microsoft.UI.Xaml.Automation.Peers...

TitleBarAutomationPeer implements ...

API Details

1[MUX_EXPERIMENTAL]
2[webhosthidden]
3unsealed runtimeclass TitleBar : Microsoft.UI.Xaml.Controls.Control
4{
5    TitleBar();
6
7    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
8    UIElement ContentBefore{ get; set; };
9
10    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
11    String Title{ get; set; };
12
13    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
14    String Subtitle{ get; set; };
15
16    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
17    Microsoft.UI.Xaml.Controls.IconSource IconSource{ get; set; };
18
19    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
20    UIElement Content{ get; set; };
21
22    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
23    UIElement ContentAfter{ get; set; };
24
25    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
26    Boolean IsBackButtonVisible{ get; set; };
27
28    Boolean IsBackButtonEnabled{ get; set; };
29
30    [MUX_PROPERTY_CHANGED_CALLBACK(TRUE)]
31    Boolean IsPaneToggleButtonVisible{ get; set; };
32
33    TitleBarTemplateSettings TemplateSettings{ get; };
34
35    event Windows.Foundation.TypedEventHandler<TitleBar, Object> BackRequested;
36    event Windows.Foundation.TypedEventHandler<TitleBar, Object> PaneToggleRequested;
37
38    static Microsoft.UI.Xaml.DependencyProperty ContentBeforeProperty{ get; };
39    static Microsoft.UI.Xaml.DependencyProperty TitleProperty{ get; };
40    static Microsoft.UI.Xaml.DependencyProperty SubtitleProperty{ get; };
41    static Microsoft.UI.Xaml.DependencyProperty IconSourceProperty{ get; };
42    static Microsoft.UI.Xaml.DependencyProperty ContentProperty{ get; };
43    static Microsoft.UI.Xaml.DependencyProperty ContentAfterProperty{ get; };
44    static Microsoft.UI.Xaml.DependencyProperty IsBackButtonVisibleProperty{ get; };
45    static Microsoft.UI.Xaml.DependencyProperty IsBackButtonEnabledProperty{ get; };
46
47    static Microsoft.UI.Xaml.DependencyProperty TemplateSettingsProperty{ get; };
48}
49
50[MUX_EXPERIMENTAL]
51[webhosthidden]
52unsealed runtimeclass TitleBarTemplateSettings : Microsoft.UI.Xaml.DependencyObject
53{
54    TitleBarTemplateSettings();
55
56    Microsoft.UI.Xaml.Controls.IconElement IconElement;
57
58    static Microsoft.UI.Xaml.DependencyProperty IconElementProperty{ get; };
59}
60
61[MUX_EXPERIMENTAL]
62[webhosthidden]
63unsealed runtimeclass TitleBarAutomationPeer : Microsoft.UI.Xaml.Automation.Peers.FrameworkElementAutomationPeer
64{
65    TitleBarAutomationPeer(MEU_XC_NAMESPACE.TitleBar owner);
66}

ThemeResources

This section does not list all of the ThemeResources associated with TitleBar. Only ThemeResources of note that require highlight or further explanation.

TitleBar currently overwrites the resources on theme changes in codebehind. This can be removed once the theme change feature is shipped for AppWindow.

There is no TitleBar.Height property. The height for TitleBar is configured in codebehind depending on whether there is content present in the ContentBefore, Content, and ContentAfter content areas. TitleBar's height is set to TitleBarCompactHeight if no elements are present in the mentioned content areas, and TitleBarExpandedHeight if elements are present. As the content areas are empty by default, the default height for TitleBar is TitleBarCompactHeight.

Figma link

Figma link

Appendix

Reference:

• Tammy's TitleBar WIP
• Niels Laute's TitleBar in CommunityToolkit: PR, Spec