TitleBar

TitleBar provides a customizable window title bar that can replace the default OS title bar. It includes platform-specific window controls (minimize, maximize, close) and supports custom content and styling. The component automatically adapts to different operating systems (macOS, Windows, Linux) with appropriate behaviors and visual styles.

Import

use gpui_component::TitleBar;

Usage

Basic Title Bar

TitleBar::new()
    .child(div().child("My Application"))

Title Bar with Custom Content

TitleBar::new()
    .child(
        div()
            .flex()
            .items_center()
            .gap_3()
            .child("App Name")
            .child(Badge::new().count(5))
    )
    .child(
        div()
            .flex()
            .items_center()
            .gap_2()
            .child(Button::new("settings").icon(IconName::Settings))
            .child(Button::new("profile").icon(IconName::User))
    )

Title Bar with Menu Bar

TitleBar::new()
    .child(
        div()
            .flex()
            .items_center()
            .child(AppMenuBar::new(window, cx))
    )
    .child(
        div()
            .flex()
            .items_center()
            .justify_end()
            .gap_2()
            .child(Button::new("github").icon(IconName::GitHub))
            .child(Button::new("notifications").icon(IconName::Bell))
    )

Title Bar with Window Controls (Linux only)

TitleBar::new()
    .on_close_window(|_, window, cx| {
        // Custom close behavior
        window.push_notification("Saving before close...", cx);
        // Perform cleanup
        window.remove_window();
    })
    .child(div().child("Custom Close Behavior"))

Styled Title Bar

TitleBar::new()
    .bg(cx.theme().primary)
    .border_color(cx.theme().primary_border)
    .child(
        div()
            .text_color(cx.theme().primary_foreground)
            .child("Styled Title Bar")
    )

Title Bar Options for Window

use gpui::{WindowOptions, TitlebarOptions};

WindowOptions {
    titlebar: Some(TitleBar::title_bar_options()),
    ..Default::default()
}

Platform Differences

macOS

• Uses native traffic light buttons (minimize, maximize, close)
• Traffic light position is automatically set to (9px, 9px)
• Double-click behavior calls window.titlebar_double_click()
• Left padding accounts for traffic light buttons (80px)
• Appears transparent by default

Windows

• Custom window control buttons with system integration
• Uses WindowControlArea for proper window management
• Control buttons have hover and active states
• Fixed button width of 34px each
• Left padding is 12px

Linux

• Custom window control buttons with manual event handling
• Supports custom close window callback via on_close_window()
• Double-click to maximize/restore window
• Right-click shows window context menu
• Window dragging supported in title bar area

API Reference

TitleBar

Method	Description
new()	Create a new title bar
child(element)	Add child element to the title bar
on_close_window(fn)	Custom close window handler (Linux only)
title_bar_options()	Get default titlebar options for window

Window Configuration

Property	Description
appears_transparent	Make title bar transparent (default: true)
traffic_light_position	Position of macOS traffic lights
title	Window title (optional when using custom title bar)

Title Bar Element (Internal)

The TitleBarElement provides window dragging functionality on Linux platforms.

Constants

Constant	Value	Description
TITLE_BAR_HEIGHT	34px	Standard title bar height
TITLE_BAR_LEFT_PADDING	80px (macOS), 12px (others)	Left padding for content

Examples

Application Title Bar

use gpui_component::{TitleBar, button::Button, menu::AppMenuBar};

struct AppTitleBar {
    app_menu_bar: Entity<AppMenuBar>,
}

impl Render for AppTitleBar {
    fn render(&mut self, window: &mut Window, cx: &mut Context<Self>) -> impl IntoElement {
        TitleBar::new()
            .child(
                div()
                    .flex()
                    .items_center()
                    .child(self.app_menu_bar.clone())
            )
            .child(
                div()
                    .flex()
                    .items_center()
                    .justify_end()
                    .gap_2()
                    .child(
                        Button::new("settings")
                            .ghost()
                            .icon(IconName::Settings)
                    )
                    .child(
                        Button::new("help")
                            .ghost()
                            .icon(IconName::HelpCircle)
                    )
            )
    }
}

Title Bar with Breadcrumbs

TitleBar::new()
    .child(
        div()
            .flex()
            .items_center()
            .gap_2()
            .child("Home")
            .child(IconName::ChevronRight)
            .child("Documents")
            .child(IconName::ChevronRight)
            .child("Project")
    )
    .child(
        div()
            .flex()
            .items_center()
            .gap_1()
            .child(Button::new("search").icon(IconName::Search).ghost())
            .child(Button::new("more").icon(IconName::MoreHorizontal).ghost())
    )

Custom Themed Title Bar

TitleBar::new()
    .h(px(40.)) // Custom height
    .bg(cx.theme().accent)
    .border_b_2()
    .border_color(cx.theme().accent_border)
    .child(
        div()
            .flex()
            .items_center()
            .text_color(cx.theme().accent_foreground)
            .font_weight_semibold()
            .child("Custom Theme App")
    )

Title Bar with Status

TitleBar::new()
    .child(
        div()
            .flex()
            .items_center()
            .gap_3()
            .child("My Editor")
            .child(
                div()
                    .text_xs()
                    .text_color(cx.theme().muted_foreground)
                    .child("● Unsaved changes")
            )
    )
    .child(
        div()
            .flex()
            .items_center()
            .gap_2()
            .child(
                div()
                    .text_xs()
                    .text_color(cx.theme().muted_foreground)
                    .child("Line 42, Col 12")
            )
            .child(
                Button::new("sync")
                    .small()
                    .ghost()
                    .icon(IconName::RotateCcw)
                    .tooltip("Sync changes")
            )
    )

Minimal Title Bar

TitleBar::new()
    .child(
        div()
            .text_center()
            .flex_1()
            .child("Document.txt")
    )

Title Bar with Search

TitleBar::new()
    .child(
        div()
            .flex()
            .items_center()
            .gap_3()
            .child("File Explorer")
            .child(
                Input::new("search")
                    .placeholder("Search files...")
                    .w(px(200.))
                    .small()
            )
    )

Accessibility

Keyboard Navigation

• Title bar elements are keyboard accessible
• Tab navigation works normally within title bar content
• Custom elements should implement proper focus management

Screen Reader Support

• Window control buttons have appropriate labels
• Custom content should include proper ARIA attributes
• Title information is announced correctly

Window Management

• Standard window controls work with assistive technologies
• Keyboard shortcuts (Alt+F4, etc.) function normally
• Custom close handlers should maintain expected behavior

Focus Management

• Focus is properly managed during window operations
• Title bar content participates in normal tab order
• Custom interactive elements should handle focus correctly

Notes

• The title bar automatically handles platform-specific styling and behavior
• Window controls are only rendered on Windows and Linux platforms
• The component integrates with GPUI's window management system
• Custom styling should consider platform conventions
• Window dragging is handled automatically in appropriate areas