Titlebar Customization

Klassy provides extensive titlebar customization options, allowing you to fine-tune spacing, margins, colors, and visual appearance to match your workflow and aesthetic preferences.

Titlebar Colors

Titlebar colors are read from your active color scheme and can be further customized in Klassy Settings.

Color Sources

Klassy reads titlebar colors from the color scheme in priority order:

Header section (preferred)

[Colors:Header]
BackgroundNormal=41,44,48
ForegroundNormal=252,252,252

[Colors:Header][Inactive]
BackgroundNormal=32,35,38
ForegroundNormal=161,169,177

Window Manager section (fallback)

[WM]
activeBackground=70,75,81,191
activeForeground=252,252,252
inactiveBackground=42,46,50
inactiveForeground=161,169,177

The fourth value in background colors is the alpha channel (0-255) for transparency.

Match Titlebar to Application Color

Force titlebar to match the application window color:

<!-- From breezesettingsdata.kcfg -->
<entry name="MatchTitleBarToApplicationColor" type="Bool">
    <default>false</default>
</entry>

When Disabled (Default)
When Enabled

Titlebar uses colors from the color scheme’s [WM] or [Colors:Header] section.

Titlebar matches the application’s window background color. Klassy automatically adjusts text color for proper contrast.

// From decorationcolors.cpp
if (decorationSettings->matchTitleBarToApplicationColor()) {
    ColorTools::getHigherContrastForegroundColor(
        titleBarText,
        titleBarBase,
        1.5,  // Minimum contrast ratio
        titleBarText
    );
}

When matching application colors, some applications with very light or dark backgrounds may result in poor contrast. Klassy attempts to correct this automatically.

Titlebar Spacing

Precise control over titlebar dimensions and margins:

Top and Bottom Margins

Configuration
Usage

<entry name="TitleBarTopMargin" type="Double">
   <default>3.6</default>
   <min>0</min>
   <max>50</max>
</entry>

<entry name="TitleBarBottomMargin" type="Double">
   <default>3.6</default>
   <min>0</min>
   <max>50</max>
</entry>

<entry name="LockTitleBarTopBottomMargins" type="Bool">
    <default>true</default>
</entry>

Left and Right Margins

<entry name="TitleBarLeftMargin" type="Int">
   <default>0</default>
   <min>0</min>
   <max>60</max>
</entry>

<entry name="TitleBarRightMargin" type="Int">
   <default>0</default>
   <min>0</min>
   <max>60</max>
</entry>

<entry name="LockTitleBarLeftRightMargins" type="Bool">
    <default>true</default>
</entry>

Use left/right margins to create space between the window edge and buttons, useful for ultra-wide monitors or specific aesthetic preferences.

Maximized Window Margins

Different margins for maximized windows:

<entry name="PercentMaximizedTopBottomMargins" type="Int">
   <default>85</default>
   <min>0</min>
   <max>100</max>
</entry>

This allows reducing titlebar height when windows are maximized (default: 85% of normal margins).

Setting this to 100 keeps maximized margins the same as floating windows. Lower values create more compact titlebars.

Title Text Customization

Title Alignment

<entry name="TitleAlignment" type="Enum">
  <choices>
      <choice name="AlignLeft" />
      <choice name="AlignCenter" />
      <choice name="AlignCenterFullWidth" />
      <choice name="AlignRight" />
  </choices>
  <default>AlignCenterFullWidth</default>
</entry>

AlignLeft
AlignCenter
AlignCenterFullWidth
AlignRight

Title text aligned to the left, after the left button group.

Title Side Padding

<entry name="TitleSidePadding" type="Int">
   <default>4</default>
   <min>0</min>
   <max>60</max>
</entry>

Space between title text and adjacent buttons or window edges.

Title Text Formatting

Bold Title
Underline Title

<entry name="BoldTitle" type="Bool">
    <default>true</default>
</entry>

Makes window title text bold for better readability.

<entry name="UnderlineTitle" type="Bool">
    <default>false</default>
</entry>

Underlines window title text (uncommon, disabled by default).

Titlebar Visual Effects

Background Gradient

<entry name="DrawBackgroundGradient" type="Bool">
    <default>false</default>
</entry>

Enables a subtle vertical gradient in the titlebar background for depth.

Titlebar Separator

<entry name="DrawTitleBarSeparator" type="Bool">
    <default>true</default>
</entry>

Draws a thin line separating the titlebar from the application content.

The separator is especially useful with transparent titlebars to maintain visual distinction from window content.

Border Customization

Border Colors

<entry name="UseTitleBarColorForAllBorders" type="Bool">
    <default>true</default>
</entry>

When Enabled (Default)
When Disabled

All window borders match the titlebar color for a cohesive appearance.

Maximized Window Borders

<entry name="DrawBorderOnMaximizedWindows" type="Bool">
    <default>false</default>
</entry>

Controls whether maximized windows show borders (typically disabled to maximize screen space).

Window Corners

Corner Radius

<entry name="WindowCornerRadius" type="Double">
   <default>4</default>
   <min>0</min>
   <max>24.0</max>
</entry>

Controls the roundness of window corners (in pixels).

Default (4px)
Sharp (0px)
Rounded (8-12px)

Subtle rounded corners matching modern design trends.

All Corners Rounded

<entry name="RoundAllCornersWhenNoBorders" type="Bool">
    <default>true</default>
</entry>

When borders are hidden, this option rounds all four corners instead of just the top corners.

Titlebar Opacity

See the Opacity & Blur guide for detailed transparency configuration. Quick reference:

<entry name="ActiveTitleBarOpacity" type="Int">
   <default>100</default>
   <min>0</min>
   <max>100</max>
</entry>

<entry name="InactiveTitleBarOpacity" type="Int">
   <default>100</default>
   <min>0</min>
   <max>100</max>
</entry>

HiDPI Scaling

All titlebar spacing and margins automatically scale with HiDPI displays:

Automatic detection

Klassy detects your display scaling factor from the system.

Proportional scaling

All margins, padding, and spacing values scale proportionally.

Pixel-perfect rendering

Klassy ensures crisp rendering at any scale factor through proper pixel alignment.

Margins and spacing are specified in logical pixels and automatically convert to physical pixels based on your display scaling.

Configuration Examples

Compact Titlebar

# In klassyrc
[Windeco]
TitleBarTopMargin=2
TitleBarBottomMargin=2
TitleBarLeftMargin=0
TitleBarRightMargin=0
PercentMaximizedTopBottomMargins=70

Spacious Titlebar

[Windeco]
TitleBarTopMargin=6
TitleBarBottomMargin=6
TitleBarLeftMargin=8
TitleBarRightMargin=8
PercentMaximizedTopBottomMargins=100

MacOS-Style

[Windeco]
TitleAlignment=AlignCenterFullWidth
BoldTitle=false
DrawTitleBarSeparator=false
TitleBarTopMargin=4
TitleBarBottomMargin=4

Best Practices

Test with different content

Preview your titlebar settings with various applications (browsers, terminals, IDEs) to ensure consistent appearance.

Consider screen size

Larger margins work well on high-resolution displays, while compact margins maximize space on smaller screens.

Balance with button size

Coordinate titlebar margins with button sizing for proportional appearance.

Use maximized-specific margins

Reduce margins for maximized windows to maximize usable space while maintaining aesthetics for floating windows.

Get Started

Theming

Configuration

Guides

Titlebar Customization

Titlebar Colors

Color Sources

Match Titlebar to Application Color

Titlebar Spacing

Top and Bottom Margins

Left and Right Margins

Maximized Window Margins

Title Text Customization

Title Alignment

Title Side Padding

Title Text Formatting

Titlebar Visual Effects

Background Gradient

Titlebar Separator

Border Customization

Border Colors

Maximized Window Borders

Window Corners

Corner Radius

All Corners Rounded

Titlebar Opacity

HiDPI Scaling

Configuration Examples

Compact Titlebar

Spacious Titlebar

MacOS-Style

Best Practices

Build docs developers (and LLMs) love

Get Started

Theming

Configuration

Guides

Documentation Index

​Titlebar Colors

​Color Sources

​Match Titlebar to Application Color

​Titlebar Spacing

​Top and Bottom Margins

​Left and Right Margins

​Maximized Window Margins

​Title Text Customization

​Title Alignment

​Title Side Padding

​Title Text Formatting

​Titlebar Visual Effects

​Background Gradient

​Titlebar Separator

​Border Customization

​Border Colors

​Maximized Window Borders

​Window Corners

​Corner Radius

​All Corners Rounded

​Titlebar Opacity

​HiDPI Scaling

​Configuration Examples

​Compact Titlebar

​Spacious Titlebar

​MacOS-Style

​Best Practices

Build docs developers (and LLMs) love

Titlebar Colors

Color Sources

Match Titlebar to Application Color

Titlebar Spacing

Top and Bottom Margins

Left and Right Margins

Maximized Window Margins

Title Text Customization

Title Alignment

Title Side Padding

Title Text Formatting

Titlebar Visual Effects

Background Gradient

Titlebar Separator

Border Customization

Border Colors

Maximized Window Borders

Window Corners

Corner Radius

All Corners Rounded

Titlebar Opacity

HiDPI Scaling

Configuration Examples

Compact Titlebar

Spacious Titlebar

MacOS-Style

Best Practices