# How to Customize Themes in Tuicr: Complete Configuration Guide

> Easily customize themes in Tuicr with our complete configuration guide. Learn to use command-line flags, config.toml, or custom .tmTheme files to personalize your experience.

- Repository: [Almog Gavra/tuicr](https://github.com/agavra/tuicr)
- Tags: how-to-guide
- Published: 2026-08-01

---

**You can customize themes in Tuicr using the `--theme` command-line flag, the [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) configuration file, or by adding custom `.tmTheme` files to the themes directory.**

Tuicr is a terminal-based code review tool that provides extensive theming capabilities through its **Theme** struct defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs). The architecture supports both built-in preset color schemes and user-provided TextMate themes, allowing complete control over panel backgrounds, diff highlights, file-status colors, and status-bar styling.

## Selecting a Built-In Theme

Tuicr offers three methods to activate a theme, with command-line arguments taking precedence over configuration files.

### Command-Line Flag

Use the `--theme` flag to override any configuration file setting when launching the application. This is ideal for testing different palettes or running multiple instances with distinct appearances.

```bash
tuicr --theme solarized_dark

```

The flag accepts any built-in preset name or the basename of a custom `.tmTheme` file stored in the themes directory.

### Configuration File

For persistent theming, create a [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) in the appropriate XDG configuration directory. On Unix systems, this is `$XDG_CONFIG_HOME/tuicr/config.toml` (typically `~/.config/tuicr/config.toml`); on Windows, use `%APPDATA%\tuicr\config.toml`.

```toml
theme = "catppuccin_mocha"

```

The `theme` key must match one of the built-in preset identifiers or a custom theme filename (without extension).

### Default Fallback

If no explicit theme is specified, Tuicr falls back to `Theme::default()`, which currently returns `Theme::dark()` as defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) lines 101-138. The system does not currently auto-detect terminal background color, defaulting to the dark palette.

## Adding Custom Themes

Tuicr supports TextMate `.tmTheme` files for users who want to extend beyond the nine built-in presets (Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest).

### Creating a Custom Theme

Write a standard `.tmTheme` XML file defining your color palette. Tuicr uses the **syntect** crate to parse these themes via `ThemeSet::load_from_reader`.

### Installation Location

Place your `.tmTheme` file in the Tuicr themes directory:

- **Unix:** `$XDG_CONFIG_HOME/tuicr/themes/`
- **Windows:** `%APPDATA%\tuicr\themes\`

### Activation

The filename (minus the `.tmTheme` extension) becomes the theme identifier. For example, installing `my-custom.tmTheme` allows activation via:

```bash
tuicr --theme my-custom

```

The loader uses the `themes_dir` helper function located at line 16 of [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) to locate and parse these files.

## How Themes are Applied Internally

Understanding the internal architecture helps when debugging theme issues or contributing to the codebase.

### Core Theme Structure

The **Theme** struct in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 101-138) defines the default dark and light constructors, while lines 140-400 implement the preset themes. This struct supplies every color used by the UI, from diff addition highlights to comment-type hues.

### Style Translation Layer

UI components do not access Theme fields directly. Instead, they use helper functions in [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) that accept a `&Theme` reference and return `ratatui::style::Style` objects. Key helpers include:

- `styles::diff_add_style(&theme)` – line 13
- `styles::status_bar_style(&theme)` – line 65

### Application Flow

When Tuicr initializes, the `App` struct (constructed in [`src/app/init.rs`](https://github.com/agavra/tuicr/blob/main/src/app/init.rs) or [`src/app/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/app/mod.rs)) stores a `theme: Theme` instance. This instance is populated by reading the `theme` setting from CLI arguments or [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) via [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs). All rendering modules—including [`src/ui/app_layout.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/app_layout.rs), [`src/ui/status_bar.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/status_bar.rs), and [`src/ui/submit_modals.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/submit_modals.rs)—pull colors from this single source of truth, ensuring consistent theming across the interface.

## Summary

- **Tuicr themes** are controlled via the `--theme` flag, [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml), or default to the dark palette.
- **Built-in presets** include Solarized, Catppuccin, Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest, defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs).
- **Custom themes** use standard `.tmTheme` files placed in `$XDG_CONFIG_HOME/tuicr/themes/` or `%APPDATA%\tuicr\themes\`.
- **Internal implementation** uses the **Theme** struct parsed by [`src/config/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/config/mod.rs) and rendered through helper functions in [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) that generate **ratatui** style objects.

## Frequently Asked Questions

### How do I find the list of available built-in themes in Tuicr?

The built-in themes are defined as constructors in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) between lines 140-400. Available options include `solarized_dark`, `solarized_light`, `catppuccin_mocha`, `catppuccin_latte`, `ayu_dark`, `one_dark`, `github_light`, `tokyo_night`, `gruvbox_dark`, `nord`, and `everforest`. You can also view the current list by checking the Theme implementation in the source code or running `tuicr --help` to see example values.

### Can I use my existing VS Code theme with Tuicr?

Yes, if your VS Code theme is available in TextMate `.tmTheme` format. Export or convert your theme to a `.tmTheme` file, place it in your system's Tuicr themes directory (`~/.config/tuicr/themes/` on Linux/macOS or `%APPDATA%\tuicr\themes\` on Windows), and activate it using `tuicr --theme filename_without_extension`. Tuicr uses syntect's `ThemeSet::load_from_reader` to parse these files.

### Why isn't my custom theme appearing when I use the `--theme` flag?

Ensure the `.tmTheme` file is placed directly in the themes directory (not a subdirectory) and that you reference it by filename without the extension. Verify the directory path by checking the `themes_dir` helper implementation in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) line 16, which resolves the path using XDG directories on Unix or APPDATA on Windows. Also confirm the file has valid XML syntax, as syntect will fail to load malformed themes.

### Does Tuicr support automatic light/dark mode switching based on terminal settings?

Currently, no. The default theme is hardcoded to `Theme::dark()` in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) when no explicit theme is provided. While the architecture supports extending this detection in the future, you must manually specify light themes via the `--theme` flag or [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) to use palettes like `Theme::light()` or `github_light`.