How Alacritty Configures Window Decorations and DPI Scaling

Alacritty configures window decorations through the Decorations enum in src/config/window.rs and applies DPI scaling by caching the OS-reported scale_factor to automatically adjust font sizes and padding across Hi-DPI displays.

Alacritty, the GPU-accelerated terminal emulator written in Rust, handles window decorations and DPI scaling via two independent but coordinated subsystems. The terminal reads user preferences from TOML configuration files and translates them into platform-specific window attributes, while simultaneously monitoring display density to ensure consistent rendering across monitors with different pixel densities.

Understanding Window Decorations in Alacritty

Window decorations—such as title bars, borders, and control buttons—are defined by the Decorations enum and applied during the window initialization phase.

Parsing the Decorations Configuration

User preferences are deserialized in alacritty/src/config/window.rs (lines 82–89), where the Decorations enum supports four variants: Full, Transparent, Buttonless, and None. The configuration parser maps the TOML window.decorations value directly to this enum, allowing type-safe handling throughout the application.

Platform-Specific Window Creation

When Alacritty instantiates a window via alacritty/src/display/window.rs (lines 46–60), the Window::get_platform_window method translates the Decorations variant into platform-specific WindowAttributes. On Unix/X11, the code calls with_decorations(window_config.decorations != Decorations::None), which simply toggles server-side decorations on or off. On macOS, a comprehensive match block maps each variant to specific AppKit options like with_title_hidden, with_titlebar_transparent, and with_fullsize_content_view, enabling native transparent or buttonless title bars.

Runtime Decoration Management

The Window struct stores the chosen decoration mode implicitly after creation. Subsequent calls to methods like set_theme or toggle_fullscreen respect the current decoration state, ensuring consistent behavior when the user switches between windowed and full-screen modes.

DPI Scaling Implementation

DPI scaling ensures that terminal cells, fonts, and padding remain visually consistent regardless of the display's pixel density. Alacritty achieves this by caching the device's scale factor and applying it to all UI geometry calculations.

Initial Scale Factor Detection

Immediately after creating the native window in alacritty/src/display/window.rs (lines 100–106), Alacritty records the device pixel ratio: let scale_factor = window.scale_factor();. This f64 value represents the ratio between physical and logical pixels, typically 2.0 on modern Hi-DPI displays or 1.0 on standard monitors.

Scaling Padding and Font Size

Padding calculations in alacritty/src/config/window.rs (lines 123–127) use the WindowConfig::padding(&self, scale_factor: f32) method, which multiplies user-specified cell padding by the scale factor: (self.padding.x * scale_factor).floor(). This ensures pixel-perfect spacing on all displays.

Font scaling occurs in alacritty/src/window_context.rs (lines 75–80). When the configuration updates, the code compares the stored font size against the previous configuration scaled by the current scale_factor. If unchanged, it applies the scaling using self.config.font.size().scale(scale_factor), maintaining readable text density across different monitors.

Handling Dynamic DPI Changes

When the operating system emits a WindowEvent::ScaleFactorChanged event, Alacritty recomputes the font scale as scale_factor as f32 / old_scale_factor as f32. The display pipeline then propagates this new factor to re-render cell geometry, ensuring the terminal remains crisp when moved between displays with differing DPIs.

Windows-Specific DPI Awareness

On Windows, Alacritty declares DPI awareness through the application manifest in alacritty/windows/alacritty.manifest (line 5). The manifest specifies <dpiAwareness>PerMonitorV2, unaware</dpiAwareness>, which instructs Windows to notify the application of per-monitor scaling changes. This OS-level declaration ensures that the scale_factor value retrieved by the Rust code accurately reflects the current display's DPI settings.

Practical Configuration Examples

The following alacritty.toml configuration demonstrates window decoration and padding settings:

[window]

# Options: "Full", "Transparent", "Buttonless", "None"

decorations = "Transparent"

[window.padding]
x = 2
y = 2

To query the effective scale factor programmatically in Rust:

use alacritty::display::window::Window;

let factor = window.scale_factor(); // Returns f64, e.g., 2.0 on Retina displays
println!("Current DPI scale: {}", factor);

When handling display changes:

match event {
    WindowEvent::ScaleFactorChanged { scale_factor, .. } => {
        window.scale_factor = scale_factor;
        display.update_scale_factor(scale_factor as f32);
    }
    _ => {}
}

Summary

• Window decorations are controlled by the Decorations enum in alacritty/src/config/window.rs, with platform-specific implementations in alacritty/src/display/window.rs that map variants to native window attributes.
• DPI scaling relies on caching window.scale_factor() immediately after window creation, then applying this factor to padding calculations and font sizing throughout the application lifecycle.
• Dynamic updates are handled through ScaleFactorChanged events, which trigger recalculation of font scales and padding to maintain consistent appearance across monitors.
• Windows compatibility requires the PerMonitorV2 DPI awareness declaration in the application manifest to receive accurate scaling notifications from the OS.

Frequently Asked Questions

How do I disable window decorations in Alacritty?

Set window.decorations = "None" in your alacritty.toml configuration file. According to the source code in alacritty/src/display/window.rs, this value causes the platform-specific builder to call with_decorations(false) on X11 or equivalent APIs on other platforms, removing the title bar and window borders entirely.

Why does my font size change when moving Alacritty between monitors?

Alacritty automatically adjusts font sizes based on the scale_factor reported by the operating system. When you move the window to a display with a different DPI, the ScaleFactorChanged event triggers a recalculation in alacritty/src/window_context.rs, scaling the base font size by the new factor to maintain consistent visual size across Hi-DPI and standard displays.

What decoration options are available on macOS versus Linux?

Linux and other Unix systems support Full and None decorations via server-side window manager protocols. macOS supports additional variants including Transparent and Buttonless, which are implemented in alacritty/src/display/window.rs using AppKit-specific WindowAttributes methods like with_titlebar_transparent and with_fullsize_content_view.

How is DPI scaling handled on Windows?

Windows uses the PerMonitorV2 DPI awareness mode declared in alacritty/windows/alacritty.manifest, which allows the application to receive per-monitor scaling notifications. The Rust runtime then caches the scale factor from window.scale_factor() in alacritty/src/display/window.rs and applies it to all rendering calculations, ensuring proper scaling without bitmap stretching.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}