Terminal Transparency and Background Rendering Options in tuicr

Set transparent_background = true in your tuicr config to let terminal backgrounds—including transparency—show through UI panels, or disable it for solid theme-colored backgrounds.

Tuicr provides granular control over how terminal backgrounds and transparency interact with its UI. This guide explains the three mechanisms that govern background rendering in the agavra/tuicr codebase: the transparent_background configuration flag, automatic light/dark theme detection, and per-line diff background rendering.

The transparent_background Configuration Flag

The primary mechanism for terminal transparency control is the transparent_background boolean flag in the user configuration.

When enabled, tuicr's UI panels do not paint their own solid background color. This allows the terminal's native background—including any transparency effects applied by your terminal emulator—to remain visible behind panels, sidebars, and diff views. When disabled, panels render with the theme's panel_bg color, creating solid opaque surfaces.

The flag is defined in src/config/mod.rs as part of the Config struct:

// src/config/mod.rs
pub struct Config {
    pub transparent_background: Option<bool>,
    // ... other fields
}

At startup, src/main.rs (line 112) reads this value and passes it to the App constructor:

// src/main.rs
let app = App::new(config.transparent_background.unwrap_or(false));

Enabling Transparency in Config

Add this to your ~/.config/tuicr/config.toml:

# ~/.config/tuicr/config.toml

transparent_background = true

Disabling Transparency for Solid Panels

# ~/.config/tuicr/config.toml

transparent_background = false

Automatic Terminal Background Detection

Tuicr automatically detects your terminal's background color at startup to select an appropriate theme. This detection runs independently of the transparency flag but works alongside it to ensure consistent visual output.

The detection logic in src/theme/mod.rs (lines 1730–1744) uses the terminal_colorsaurus crate to query the terminal's actual background color:

// src/theme/mod.rs
fn is_terminal_background_dark() -> Option<bool> {
    terminal_colorsaurus::background_color()
        .ok()
        .map(|c| c.is_dark())
}

If terminal query fails, tuicr falls back to system dark-mode detection:

// src/theme/mod.rs
is_terminal_background_dark().or_else(is_system_dark_mode)

Detected Background	Selected Theme
Dark	Theme::dark()
Light	Theme::light()

Overriding Automatic Detection

Force a specific theme regardless of terminal background:

# ~/.config/tuicr/config.toml

theme = "light"          # or "dark"

transparent_background = false

Per-Line Diff Background Rendering

Diff views require special handling: each line needs its own background color (green for additions, red for deletions, neutral for context) while respecting the global transparency setting.

The highlighted_line_for_diff_with_background function in src/syntax/mod.rs (lines 228–242) handles this:

// src/syntax/mod.rs
pub fn highlighted_line_for_diff_with_background(
    &self,
    line: &str,
    origin: LineOrigin,
) -> Vec<Span<'static>> {
    let mut spans = self.highlight_line(line);
    apply_diff_background(&mut spans, origin);
    spans
}

The apply_diff_background helper (lines 368–383) adds the appropriate background span based on LineOrigin:

// src/syntax/mod.rs
fn apply_diff_background(spans: &mut Vec<Span>, origin: LineOrigin) {
    let bg = match origin {
        LineOrigin::Addition => DIFF_ADD_BG,
        LineOrigin::Deletion => DIFF_DELETE_BG,
        LineOrigin::Context => DIFF_CONTEXT_BG,
    };
    // Apply background to all spans in the line
}

When transparent_background is true, the surrounding panel omits its background color, allowing the terminal's transparency to show through—while the diff line itself retains its semantic coloring via span backgrounds.

How Transparency and Diff Rendering Interact

The rendering pipeline ensures diff backgrounds work correctly with transparent panels:

1. Panel rendering — If transparent_background is true, the panel skips painting panel_bg
2. Line rendering — diff_unified.rs or diff_view.rs (lines 603–1188) calls highlighted_line_for_diff_with_background
3. Span composition — Syntax highlighting runs first, then diff background is applied as an overlay
4. Final output — Ratatui renders spans with their explicit backgrounds; transparent areas show the terminal behind

Programmatic Access

Check transparency status in custom plugins or extensions:

use tuicr::config::Config;

fn is_transparent(cfg: &Config) -> bool {
    cfg.transparent_background.unwrap_or(false)
}

Internal rendering call for diff lines:

let highlighted = highlighter.highlighted_line_for_diff_with_background(
    line_text,
    line_origin,
);

Key Source Files

File	Responsibility
src/config/mod.rs (lines 132–425)	Defines Config struct and parses transparent_background
src/main.rs (line 112)	Reads flag and initializes App
src/theme/mod.rs (lines 1730–1744)	Terminal background detection and theme selection
src/syntax/mod.rs (lines 228–383)	Diff line highlighting with background spans
src/ui/diff_unified.rs / src/ui/diff_view.rs (lines 603–1188)	UI layers invoking syntax highlighter

Summary

• transparent_background — Boolean config flag in src/config/mod.rs that controls whether panels paint solid backgrounds or allow terminal transparency through
• Automatic theme detection — Uses terminal_colorsaurus in src/theme/mod.rs to choose dark/light themes based on actual terminal background color
• Diff background rendering — highlighted_line_for_diff_with_background in src/syntax/mod.rs applies per-line semantic coloring that works with or without transparency enabled
• Interaction — Diff spans carry their own backgrounds; panel transparency determines whether terminal shows through the gaps between spans

Frequently Asked Questions

How do I enable transparent backgrounds in tuicr?

Add transparent_background = true to ~/.config/tuicr/config.toml. This prevents panels from painting panel_bg, allowing your terminal's native background—including any transparency—to show through.

Does transparency affect syntax highlighting colors?

No. Syntax highlighting and diff backgrounds remain fully colored. Only the panel background becomes transparent; text spans retain their foreground and background colors as defined by the theme.

What happens if my terminal doesn't report its background color?

Tuicr falls back to system dark-mode detection via is_system_dark_mode in src/theme/mod.rs. If that also fails, it defaults to a conservative choice. You can always override with theme = "dark" or theme = "light" in config.

Can I use transparency with a specific theme?

Yes. The theme and transparent_background settings are independent. You can force a light theme with transparent panels, or a dark theme with solid backgrounds—any combination works.

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