# How to Create and Use Custom Themes in Tuicr Configuration

> Learn to create and use custom themes in Tuicr configuration. Easily add your own .tmTheme files or select from nine built-in presets to personalize your Tuicr experience.

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

---

**You can create custom themes in tuicr by placing `.tmTheme` files in the themes directory and activating them via the `--theme` flag or [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) file, or choose from nine built-in presets including Solarized, Catppuccin, and Nord.**

Tuicr is a terminal-based code review tool that supports extensive visual customization through its **Theme** system. The application uses a centralized `Theme` struct defined in the source code to manage every color used in the interface, from panel backgrounds to diff highlights. Whether you prefer built-in presets or want to import your own TextMate themes, tuicr's configuration system provides multiple pathways to customize your code review experience.

## Understanding the Theme System

### Core Theme Structure

The theme engine centers on the `Theme` struct defined in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 101-138). This structure supplies every color used by the UI, including panel backgrounds, diff highlights, file-status colors, comment-type hues, and status-bar styling. The struct provides default constructors `Theme::dark()` and `Theme::light()` that establish baseline color palettes.

### Built-in Preset Themes

Tuicr ships with nine built-in color schemes implemented in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 140-400):

- **Solarized** (dark and light variants)
- **Catppuccin** (Mocha, Macchiato, Frappe, Latte)
- **Ayu**
- **OneDark**
- **GitHub**
- **Tokyo Night**
- **Gruvbox**
- **Nord**
- **Everforest**

## Selecting a Theme

### Command-Line Flag

The fastest way to switch themes is using the `--theme` flag, which overrides any configuration file setting.

```bash
tuicr --theme solarized_dark

```

### Configuration File

For persistent theming, create a [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) in your platform's 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"

```

### Default Behavior

If no theme is specified, tuicr falls back to `Theme::default()`, which currently returns `Theme::dark()`. The system is architected to allow future terminal background detection, but presently defaults to the dark palette.

## Creating and Loading Custom Themes

Tuicr supports user-defined syntax-highlighting themes through the **TextMate `.tmTheme` format**. The loader uses `crate::config::themes_dir` (defined at [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) line 16) to locate user themes and parses them using syntect's `ThemeSet::load_from_reader`.

To add a custom theme:

1. Create a `.tmTheme` file defining your color palette
2. Place it in the themes directory:
   - **Unix:** `$XDG_CONFIG_HOME/tuicr/themes/` (usually `~/.config/tuicr/themes/`)
   - **Windows:** `%APPDATA%\tuicr\themes\`
3. Reference the theme by filename (without extension)

For example, with a file named `my-custom.tmTheme`:

```bash
tuicr --theme my-custom

```

## How Themes Are Applied in the Codebase

When tuicr initializes, the `App` struct stores a `theme: Theme` instance that serves as the single source of truth for all UI colors. UI components access these colors through helper functions in [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs), which accept a `&Theme` reference and return `ratatui::style::Style` values.

Key style helpers include:

- `styles::diff_add_style(&theme)` (line 13) for diff additions
- `styles::status_bar_style(&theme)` (line 65) for status bar backgrounds

All rendering code in [`ui/app_layout.rs`](https://github.com/agavra/tuicr/blob/main/ui/app_layout.rs), [`ui/status_bar.rs`](https://github.com/agavra/tuicr/blob/main/ui/status_bar.rs), and [`ui/submit_modals.rs`](https://github.com/agavra/tuicr/blob/main/ui/submit_modals.rs) pulls colors from the `App` instance's theme through these style helpers, ensuring consistent application across the interface.

## Summary

- The **Theme** struct in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 101-138) controls all UI colors, with built-in presets defined in lines 140-400
- Activate themes via `--theme` flag, [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml), or accept the default dark theme
- Create custom themes by placing **`.tmTheme`** files in the XDG config themes directory
- The `App` struct stores the active theme, while [`src/ui/styles.rs`](https://github.com/agavra/tuicr/blob/main/src/ui/styles.rs) translates theme fields into ratatui `Style` objects for rendering

## Frequently Asked Questions

### What file format should I use for custom tuicr themes?

Tuicr uses the **TextMate `.tmTheme` format** for custom syntax highlighting themes. These XML-based files define color palettes that syntect parses using `ThemeSet::load_from_reader`. Place your `.tmTheme` files in the themes directory (e.g., `~/.config/tuicr/themes/` on Unix) and reference them by filename without the extension.

### Where does tuicr look for the configuration file?

Tuicr follows the XDG Base Directory Specification. On Unix systems, it searches for [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) in `$XDG_CONFIG_HOME/tuicr/` (defaulting to `~/.config/tuicr/`). On Windows, the configuration resides in `%APPDATA%\tuicr\config.toml`. The themes subdirectory within this path stores custom `.tmTheme` files.

### Can I override the config file theme temporarily?

Yes. The `--theme` command-line flag takes precedence over the [`config.toml`](https://github.com/agavra/tuicr/blob/main/config.toml) setting. Running `tuicr --theme <NAME>` loads the specified theme for that session only, regardless of what is saved in your configuration file. This allows quick switching without modifying persistent settings.

### Which built-in themes are available in tuicr?

Tuicr includes nine built-in color schemes: Solarized (dark/light), Catppuccin variants (Mocha, Macchiato, Frappe, Latte), Ayu, OneDark, GitHub, Tokyo Night, Gruvbox, Nord, and Everforest. These are implemented in [`src/theme/mod.rs`](https://github.com/agavra/tuicr/blob/main/src/theme/mod.rs) (lines 140-400) and can be referenced by their lowercase names with underscores (e.g., `solarized_dark`, `catppuccin_mocha`).