# Terminal Transparency and Background Rendering Options in tuicr

> Customize tuicr's terminal transparency and background rendering. Enable transparent backgrounds to see through UI panels or disable for solid colors. Configure your tuicr experience now.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: internals
- Published: 2026-08-02

---

**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`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) as part of the `Config` struct:

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

```

At startup, [`src/main.rs`](https://github.com/agavra/tuicr/blob/main/src/main.rs) (line 112) reads this value and passes it to the `App` constructor:

```rust
// 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`:

```toml

# ~/.config/tuicr/config.toml

transparent_background = true

```

### Disabling Transparency for Solid Panels

```toml

# ~/.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`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 1730–1744) uses the `terminal_colorsaurus` crate to query the terminal's actual background color:

```rust
// 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:

```rust
// 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:

```toml

# ~/.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`](https://github.com/agavra/tuicr/blob/main/src/syntax/mod.rs) (lines 228–242) handles this:

```rust
// 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`:

```rust
// 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`](https://github.com/agavra/tuicr/blob/main/diff_unified.rs) or [`diff_view.rs`](https://github.com/agavra/tuicr/blob/main/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:

```rust
use tuicr::config::Config;

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

```

Internal rendering call for diff lines:

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

```

## Key Source Files

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

## Summary

- **`transparent_background`** — Boolean config flag in [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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`](https://github.com/agavra/tuicr/blob/main/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.