Opacity & Blur Effects

Klassy provides comprehensive transparency and blur controls, allowing you to create elegant translucent titlebars with optional background blur effects.

Titlebar Opacity

Control transparency separately for active and inactive windows:

Basic Opacity Settings

<!-- From breezesettingsdata.kcfg -->
<group name="TitleBarOpacity">
    <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>
</group>

100% (Fully Opaque)
75-90% (Subtle)
50-75% (Moderate)
0-50% (High Transparency)

Default setting. Titlebar is completely solid with no transparency.

High transparency without blur can make titlebar text difficult to read, especially against busy wallpapers.

How Opacity is Applied

Klassy applies opacity to titlebar colors from your color scheme:

// From decorationcolors.cpp
bool setTitleBarBaseOpacity = false;
if (!decorationSettings->opaqueTitleBar()) {
    if (titleBarBase.alpha() == 255) {
        setTitleBarBaseOpacity = true;
    } else {
        bool override = active 
            ? decorationSettings->overrideActiveTitleBarOpacity() 
            : decorationSettings->overrideInactiveTitleBarOpacity();
        if (override) {
            setTitleBarBaseOpacity = true;
        }
    }
}
if (setTitleBarBaseOpacity) {
    titleBarBase.setAlphaF(
        qreal(active 
            ? decorationSettings->activeTitleBarOpacity() 
            : decorationSettings->inactiveTitleBarOpacity()) / 100
    );
}

Override Color Scheme Opacity

Color schemes can specify their own opacity in the alpha channel:

# In color scheme file
[WM]
activeBackground=70,75,81,191  # 191 = 75% opacity
activeBlend=252,252,252
activeForeground=252,252,252

To override this with Klassy settings:

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

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

When override is disabled, Klassy respects the color scheme’s built-in opacity. Enable override to force your configured opacity values.

Blur Effects

Background blur creates a frosted glass effect behind transparent titlebars:

Enable Blur

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

When Enabled (Default)
When Disabled

Klassy applies background blur to transparent titlebars, creating a modern frosted glass appearance.Requirements:

Compositor must be running (enabled by default in KDE Plasma)
Compositor must support blur effects
Desktop Effects must be enabled in System Settings

Blur Implementation

Klassy uses KWindowEffects for blur:

// From breezestyle.cpp
_blurHelper = std::make_unique<BlurHelper>(_helper);

The blur helper manages:

Blur region updates when window is resized
Proper blur boundaries around rounded corners
Performance optimization through region caching
Compositor compatibility checking

Blur is applied only to the titlebar and header area, not the entire window, for optimal performance.

Maximized Windows

Special handling for maximized windows:

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

When Enabled (Default)
When Disabled

Maximized windows have fully opaque titlebars (100% opacity), regardless of your opacity settings.Benefits:

Better readability in fullscreen applications
Reduced compositor overhead for maximized windows
Cleaner appearance for maximized terminal windows

This setting only affects the opacity override, not the color. Maximized windows still use the same titlebar color.

Header Area Opacity

Extend opacity to the entire header area:

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

When Enabled (Default)
When Disabled

Opacity applies to the entire header area (titlebar + any application header/toolbar area).Works with applications that use:

KDE’s Header color role
Client-side decorations (CSD)
Merged titlebar/toolbar areas

Window-Specific Opacity

Override opacity for specific windows using exceptions:

Opaque Titlebar Exception

<!-- In exception settings -->
<entry name="OpaqueTitleBar" type="Bool">
   <default>false</default>
</entry>

Force specific windows to have opaque titlebars:

Add window exception

Klassy Settings → Window-Specific Overrides → Add

Configure window pattern

Specify window class name or title pattern to match

Enable opaque titlebar

Check “Opaque titlebar” option for the exception

Useful for terminals, video players, or other applications where you always want solid titlebars.

Prevent Header Opacity

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

Prevents opacity from affecting the header area for specific windows.

Button Opacity

Separate opacity controls for button components:

Icon Opacity

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

Controls transparency of button icons themselves (separate from backgrounds).

Background Opacity

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

Default 60% opacity for button backgrounds provides subtle visibility while maintaining the clean Klassy aesthetic.

Opacity Variations

Control how opacity changes between button states:

VaryColor Options

<entry name="VaryColorBackground" type="Enum">
    <choices>
      <choice name="No" />
      <choice name="Opaque" />
      <choice name="MostOpaqueHover" />
      <choice name="Transparent" />
      <choice name="MostTransparentHover" />
      <!-- ... more options ... -->
    </choices>
    <default>Opaque</default>
</entry>

No
Opaque
MostOpaqueHover
Transparent
MostTransparentHover

No variation - same opacity for all states.

Implementation

// From decorationbuttoncolors.cpp
switch (varyColor) {
    case InternalSettings::EnumVaryColorBackground::Opaque:
        bistate1 = ColorTools::alphaMix(baseColor, 0.8);
        bistate2 = ColorTools::alphaMix(baseColor, 1.2);
        break;
    case InternalSettings::EnumVaryColorBackground::Transparent:
        bistate1 = ColorTools::alphaMix(baseColor, 1.2);
        bistate2 = ColorTools::alphaMix(baseColor, 0.8);
        break;
    // ... more cases ...
}

Performance Considerations

Blur Impact

Background blur can impact performance on:

Older GPUs
Systems with many windows
High-resolution displays (4K+)
Battery-powered devices

Optimization tips:

Disable blur on battery power
Use higher opacity (75%+) to reduce blur dependency
Reduce blur radius in compositor settings
Disable blur for maximized windows

Compositor Requirements

Blur requires a compositor with blur support:

KWin (Default)
Picom/Compton
Other Compositors

Full support for background blur effects. Enabled by default in KDE Plasma.

Configuration Examples

Frosted Glass Effect

# In klassyrc
[TitleBarOpacity]
ActiveTitleBarOpacity=75
InactiveTitleBarOpacity=60
BlurTransparentTitleBars=true
OpaqueMaximizedTitleBars=true
ApplyOpacityToHeader=true

Subtle Transparency

[TitleBarOpacity]
ActiveTitleBarOpacity=90
InactiveTitleBarOpacity=85
BlurTransparentTitleBars=true
OpaqueMaximizedTitleBars=true

Maximum Performance

[TitleBarOpacity]
ActiveTitleBarOpacity=100
InactiveTitleBarOpacity=100
BlurTransparentTitleBars=false
OpaqueMaximizedTitleBars=true

High Transparency

[TitleBarOpacity]
ActiveTitleBarOpacity=50
InactiveTitleBarOpacity=40
BlurTransparentTitleBars=true
OpaqueMaximizedTitleBars=true
ApplyOpacityToHeader=true

# Increase button background opacity for visibility
[ButtonColors]
ButtonBackgroundOpacity=80

Best Practices

Start conservative

Begin with 85-90% opacity and adjust based on preference and wallpaper.

Always enable blur for transparency

Blur significantly improves readability with transparent titlebars.

Test against your wallpaper

Ensure titlebar text remains readable against your typical wallpaper colors and patterns.

Use opaque maximized windows

Keeps fullscreen applications crisp while allowing transparency for floating windows.

Adjust button opacity independently

If button backgrounds are hard to see, increase ButtonBackgroundOpacity without changing titlebar opacity.

Monitor performance

If experiencing lag, try disabling blur or increasing opacity to reduce compositor load.

Troubleshooting

Blur Not Working

Check compositor

Ensure compositor is running: System Settings → Display → Compositor

Enable desktop effects

System Settings → Workspace Behavior → Desktop Effects → Blur

Check blur settings

System Settings → Workspace Behavior → Desktop Effects → Blur → Configure

Verify KWindowEffects

Blur requires KWindowEffects support in your compositor.

Titlebar Still Opaque

Check override settings

Ensure override opacity is enabled if your color scheme has built-in opacity.

Verify exception rules

Check that no window-specific exception is forcing opaque titlebars.

Restart application

Some applications may need restart to reflect opacity changes.

Poor Text Readability

Increase opacity

Try 75-85% as a middle ground.

Enable blur

Blur significantly improves text contrast.

Choose darker wallpaper

Or use a wallpaper with less visual noise behind windows.

Increase button background opacity

Makes interactive elements more visible.

Get Started

Theming

Configuration

Guides

Opacity & Blur Effects

Titlebar Opacity

Basic Opacity Settings

How Opacity is Applied

Override Color Scheme Opacity

Blur Effects

Enable Blur

Blur Implementation

Maximized Windows

Header Area Opacity

Window-Specific Opacity

Opaque Titlebar Exception

Prevent Header Opacity

Button Opacity

Icon Opacity

Background Opacity

Opacity Variations

VaryColor Options

Implementation

Performance Considerations

Blur Impact

Compositor Requirements

Configuration Examples

Frosted Glass Effect

Subtle Transparency

Maximum Performance

High Transparency

Best Practices

Troubleshooting

Blur Not Working

Titlebar Still Opaque

Poor Text Readability

Build docs developers (and LLMs) love

Get Started

Theming

Configuration

Guides

Documentation Index

​Titlebar Opacity

​Basic Opacity Settings

​How Opacity is Applied

​Override Color Scheme Opacity

​Blur Effects

​Enable Blur

​Blur Implementation

​Maximized Windows

​Header Area Opacity

​Window-Specific Opacity

​Opaque Titlebar Exception

​Prevent Header Opacity

​Button Opacity

​Icon Opacity

​Background Opacity

​Opacity Variations

​VaryColor Options

​Implementation

​Performance Considerations

​Blur Impact

​Compositor Requirements

​Configuration Examples

​Frosted Glass Effect

​Subtle Transparency

​Maximum Performance

​High Transparency

​Best Practices

​Troubleshooting

​Blur Not Working

​Titlebar Still Opaque

​Poor Text Readability

Build docs developers (and LLMs) love

Titlebar Opacity

Basic Opacity Settings

How Opacity is Applied

Override Color Scheme Opacity

Blur Effects

Enable Blur

Blur Implementation

Maximized Windows

Header Area Opacity

Window-Specific Opacity

Opaque Titlebar Exception

Prevent Header Opacity

Button Opacity

Icon Opacity

Background Opacity

Opacity Variations

VaryColor Options

Implementation

Performance Considerations

Blur Impact

Compositor Requirements

Configuration Examples

Frosted Glass Effect

Subtle Transparency

Maximum Performance

High Transparency

Best Practices

Troubleshooting

Blur Not Working

Titlebar Still Opaque

Poor Text Readability