Skip to content

Commit 80b5961

Browse files
jwmsftjwmsft
authored
add title bar article (#5299)
* add title bar article * fix build validation warnings
1 parent 13a39d8 commit 80b5961

File tree

5 files changed

+153
-1
lines changed

5 files changed

+153
-1
lines changed

‎hub/apps/design/basics/titlebar-design.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ keywords: windows 10, uwp
88
ms.localizationpriority: medium
99
---
1010

11-
# Title bar
11+
# Title bar design
1212

1313
The title bar sits at the top of an app on the [base layer](../signature-experiences/layering.md). Its main purpose is to allow users to be able to identify the app via its title, move the app window, and minimize, maximize, or close the app.
1414

‎hub/apps/design/controls/images/titlebar/title-bar-custom.png

8.35 KB
Loading

‎hub/apps/design/controls/images/titlebar/title-bar-parts.png

22.6 KB
Loading

‎hub/apps/design/controls/title-bar.md

Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
---
2+
description: Learn how to use a title bar control to give your app a custom title bar.
3+
title: Title bar
4+
label: Tile bar
5+
template: detail.hbs
6+
op-migration-status: ready
7+
ms.date: 03/31/2025
8+
ms.topic: article
9+
doc-status: Published
10+
ms.localizationpriority: medium
11+
---
12+
# Title bar
13+
14+
The TitleBar control provides a simplified way to create a custom title bar for your app. The title bar is a fundamental component of a Windows app's user interface that identifies the app via its icon and title, houses the system caption buttons that let a user close, maximize, minimize, and restore the window, and lets a user drag the window around the screen.
15+
16+
You can use a custom title bar to better integrate the title bar area with your app UI. The title bar can be customized to match the app's visual style using Mica theming. It can include other relevant information, such as a document title or the current state (e.g., “Editing,” “Viewing,” etc.). It can also host other WinUI controls, like AutoSuggestBox and PersonPicture, providing a cohesive user experience for your app.
17+
18+
![Screenshot of an app window with a custom title bar](images/titlebar/title-bar-custom.png)
19+
20+
## Is this the right control?
21+
22+
Use the TitleBar control when you want to integrate the title bar area with your app UI using customizations such as subtitles, [Mica](../style/mica.md) theming, and integrations with WinUI controls.
23+
24+
## Anatomy
25+
26+
By default, the title bar shows only the system caption buttons. Other parts of the title bar are shown or hidden depending on associated property settings.
27+
28+
The title bar is divided into these areas:
29+
30+
![Screenshot showing the parts of a title bar control.](images/titlebar/title-bar-parts.png)
31+
32+
- **Back button:** [IsBackButtonEnabled](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [IsBackButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonvisible), [BackRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.backrequested) - A built-in back button for navigation.
33+
- **Pane toggle button:** [IsPaneToggleButtonVisible](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.isbackbuttonenabled), [PaneToggleRequested](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.panetogglerequested) - This button is intended to be used in conjunction with the NavigationView control.
34+
- **Left header:** [LeftHeader](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.leftheader)
35+
- **Icon:** [IconSource](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.iconsource)
36+
- **Title:** [Title](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.title)
37+
- **Subtitle:** [Subtitle](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.subtitle)
38+
- **Content:** [Content](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.content)
39+
- **Right header:** [RightHeader](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.rightheader)
40+
- **Min drag region:** This area is reserved next to the system caption buttons so that the user always has a place to grab the window for dragging.
41+
- **System caption buttons:** These buttons are not part of the TitleBar control - it simply allocates space where the caption buttons appear, depending on RTL or LTR settings. Caption buttons and customizations are handled by the [AppWindowTitleBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.windowing.appwindowtitlebar).
42+
43+
The layout is reversed when the [FlowDirection](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.frameworkelement.flowdirection) is **RightToLeft**.
44+
45+
## Create a title bar
46+
47+
> [!div class="checklist"]
48+
>
49+
> - **Important APIs:** [TitleBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar), [Title property](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar.title)
50+
51+
> [!div class="nextstepaction"]
52+
> [Open the WinUI 3 Gallery app and see the TitleBar in action](winui3gallery:/item/TitleBar)
53+
54+
[!INCLUDE [winui-3-gallery](../../../includes/winui-3-gallery.md)]
55+
56+
This example creates a simple title bar that replaces the system title bar. It has a title, icon, and Mica theming.
57+
58+
```xaml
59+
<Window
60+
... >
61+
<Window.SystemBackdrop>
62+
<MicaBackdrop Kind="Base"/>
63+
</Window.SystemBackdrop>
64+
65+
<Grid>
66+
<Grid.RowDefinitions>
67+
<RowDefinition Height="Auto" />
68+
<RowDefinition Height="*" />
69+
</Grid.RowDefinitions>
70+
71+
<TitleBar x:Name="SimpleTitleBar"
72+
Title="My App">
73+
<TitleBar.IconSource>
74+
<FontIconSource Glyph="&#xF4AA;"/>
75+
</TitleBar.IconSource>
76+
</TitleBar>
77+
78+
<!-- App content -->
79+
<Frame x:Name="RootFrame" Grid.Row="1"/>
80+
</Grid>
81+
</Window>
82+
```
83+
84+
```csharp
85+
public MainWindow()
86+
{
87+
this.InitializeComponent();
88+
89+
// Hides the default system title bar.
90+
ExtendsContentIntoTitleBar = true;
91+
// Replace system title bar with the WinUI TitleBar control.
92+
SetTitleBar(SimpleTitleBar);
93+
}
94+
95+
```
96+
97+
## Integration with NavigationView
98+
99+
The [Navigation view](navigationview.md) has a built-in back button and pane toggle button. Fluent Design guidance recommends that these controls be placed in the title bar when a custom title bar is used.
100+
101+
This example demonstrates how to integrate the TitleBar control with a NavigationView control by hiding the back button and pane toggle button in the navigation view and using the corresponding buttons on the title bar instead.
102+
103+
```xaml
104+
<Grid>
105+
<Grid.RowDefinitions>
106+
<RowDefinition Height="Auto" />
107+
<RowDefinition Height="*" />
108+
</Grid.RowDefinitions>
109+
110+
<TitleBar Title="My App"
111+
IsBackButtonVisible="True"
112+
IsBackButtonEnabled="{x:Bind RootFrame.CanGoBack, Mode=OneWay}"
113+
BackRequested="TitleBar_BackRequested"
114+
IsPaneToggleButtonVisible="True"
115+
PaneToggleRequested="TitleBar_PaneToggleRequested">
116+
</TitleBar>
117+
118+
<NavigationView x:Name="RootNavigationView" Grid.Row="1"
119+
IsBackButtonVisible="Collapsed"
120+
IsPaneToggleButtonVisible="False">
121+
<Frame x:Name="RootFrame" />
122+
</NavigationView>
123+
</Grid>
124+
```
125+
126+
```csharp
127+
private void TitleBar_BackRequested(TitleBar sender, object args)
128+
{
129+
if (RootFrame.CanGoBack)
130+
{
131+
RootFrame.GoBack();
132+
}
133+
}
134+
135+
private void TitleBar_PaneToggleRequested(TitleBar sender, object args)
136+
{
137+
RootNavigationView.IsPaneOpen = !RootNavigationView.IsPaneOpen;
138+
}
139+
140+
```
141+
142+
## UWP and WinUI 2
143+
144+
The TitleBar control is not available for UWP and WinUI 2. Instead, see [Title bar customization (UWP apps)](/windows/uwp/ui-input/title-bar).
145+
146+
## Related articles
147+
148+
- [Title bar (design)](../basics/titlebar-design.md)
149+
- [Title bar customization](../../develop/title-bar.md)
150+
- [TitleBar class](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.titlebar)

‎hub/apps/design/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -296,6 +296,8 @@
296296
href: controls/content-links.md
297297
- name: Handwriting view
298298
href: controls/text-handwriting-view.md
299+
- name: Title bar
300+
href: controls/title-bar.md
299301
- name: Shell
300302
items:
301303
- name: Overview

0 commit comments

Comments
 (0)