raffi 0.25.0

---
title: Themes
description: Dark and light themes with custom color palettes
---

import { Aside, Tabs, TabItem } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import lightThemeScreenshot from '../../../assets/screenshots/light-theme.png';
import mainScreenshot from '../../../assets/screenshots/main.png';
import catppuccinScreenshot from '../../../assets/screenshots/theme-catppuccin.png';
import nordScreenshot from '../../../assets/screenshots/theme-nord.png';
import gruvboxScreenshot from '../../../assets/screenshots/theme-gruvbox.png';
import solarizedScreenshot from '../../../assets/screenshots/theme-solarized-light.png';
import tokyoNightScreenshot from '../../../assets/screenshots/theme-tokyonight.png';

The native interface supports dark and light themes with full color customization.

<Aside type="note">
Themes are only available in **native mode**. Fuzzel mode uses system Fuzzel configuration.
</Aside>

## Built-in Themes

Raffi includes built-in dark and light theme presets:

- **`dark`** — Sleek Obsidian dark palette (default)
- **`light`** — Rose Pine Dawn light palette
- **`catppuccin`** / **`catppuccin-mocha`** — Catppuccin Mocha dark palette
- **`catppuccin-latte`** — Catppuccin Latte light palette
- **`tokyo-night`** / **`tokyonight`** — Tokyo Night dark palette
- **`nord`** — Nord dark palette
- **`gruvbox`** — Gruvbox dark palette
- **`dracula`** — Dracula dark palette
- **`rose-pine`** / **`rosepine`** — Rosé Pine dark palette
- **`kanagawa`** — Kanagawa Wave dark palette

## Selecting a Theme

### Command Line

<Tabs>
<TabItem label="Dark Theme (Default)">
```bash
raffi -u native -t dark
```
</TabItem>
<TabItem label="Light Theme">
```bash
raffi -u native -t light
```
</TabItem>
<TabItem label="Named Preset">
```bash
raffi -u native -t catppuccin
```
</TabItem>
</Tabs>

### Configuration File

```yaml raffi.yaml
general:
  theme: dark  # or "light", "catppuccin", "tokyo-night", "nord", "gruvbox", "dracula", "rose-pine", "kanagawa"
```

<Tabs>
  <TabItem label="Dark Theme">
    ```yaml
    general:
      ui_type: native
      theme: dark
    ```

    Sleek Obsidian dark palette with crisp slate text and indigo accents
  </TabItem>

  <TabItem label="Light Theme">
    ```yaml
    general:
      ui_type: native
      theme: light
    ```

    <Image src={lightThemeScreenshot} alt="Light theme example" width={800} />
  </TabItem>
</Tabs>

## Terminal Colours

Each theme also has its own 16-colour terminal palette, taken from the theme's terminal port. Raffi uses it for basic ANSI colours in previews and Script Filter titles, so `\e[31m` is the theme's red rather than a generic one. 256-colour and 24-bit colours are drawn as given. A palette colour that would be unreadable on the preview background, such as black on a dark theme, is replaced: a bright colour by its normal shade, otherwise by the muted text colour.

Preview commands and Script Filter previews receive the theme in the environment, so they can match their own colours to it:

| Variable | Value |
|---|---|
| `RAFFI_THEME` | Theme name, such as `catppuccin-mocha` or `dark` |
| `RAFFI_THEME_MODE` | `dark` or `light` |
| `RAFFI_THEME_FG`, `RAFFI_THEME_MUTED`, `RAFFI_THEME_ACCENT`, `RAFFI_THEME_BG` | Main text, muted text, accent and background colours as `#rrggbb`, after any `theme_colors` overrides |

The [bundled file previewer](../file-browser/#rich-previews) uses these to pick a matching `bat` and Markdown theme.

## Custom Colors

Individual theme colors can be customized under `theme_colors`. Only the colors you specify are overridden; the rest come from the base theme.

### Available Color Keys

**`bg_base`** `string`

Main background color


**`bg_input`** `string`

Search input background color


**`accent`** `string`

Primary accent color (highlights, active items)


**`accent_hover`** `string`

Accent color on hover


**`text_main`** `string`

Primary text color


**`text_muted`** `string`

Secondary/muted text color


**`selection_bg`** `string`

Selected item background


**`border`** `string`

Border and separator colors


### Color Format

Colors accept hex color strings in these formats:

- `#RGB` - Short form (e.g., `#f0f`)
- `#RRGGBB` - Standard form (e.g., `#ff00ff`)
- `#RRGGBBAA` - With alpha channel (e.g., `#ff00ff80`)

## Custom Color Examples

### Catppuccin Mocha

```yaml raffi.yaml
general:
  theme: dark
  theme_colors:
    bg_base: "#1e1e2e"
    bg_input: "#313244"
    accent: "#cba6f7"
    accent_hover: "#89b4fa"
    text_main: "#cdd6f4"
    text_muted: "#6c7086"
    selection_bg: "#45475a"
    border: "#585b70"
```

### Nord

```yaml raffi.yaml
general:
  theme: dark
  theme_colors:
    bg_base: "#2e3440"
    bg_input: "#3b4252"
    accent: "#88c0d0"
    accent_hover: "#81a1c1"
    text_main: "#eceff4"
    text_muted: "#d8dee9"
    selection_bg: "#434c5e"
    border: "#4c566a"
```

### Gruvbox Dark

```yaml raffi.yaml
general:
  theme: dark
  theme_colors:
    bg_base: "#282828"
    bg_input: "#3c3836"
    accent: "#d79921"
    accent_hover: "#fabd2f"
    text_main: "#ebdbb2"
    text_muted: "#a89984"
    selection_bg: "#504945"
    border: "#665c54"
```

### Solarized Light

```yaml raffi.yaml
general:
  theme: light
  theme_colors:
    bg_base: "#fdf6e3"
    bg_input: "#eee8d5"
    accent: "#268bd2"
    accent_hover: "#2aa198"
    text_main: "#657b83"
    text_muted: "#93a1a1"
    selection_bg: "#eee8d5"
    border: "#93a1a1"
```

### Tokyo Night

```yaml raffi.yaml
general:
  theme: dark
  theme_colors:
    bg_base: "#1a1b26"
    bg_input: "#24283b"
    accent: "#7aa2f7"
    accent_hover: "#bb9af7"
    text_main: "#c0caf5"
    text_muted: "#565f89"
    selection_bg: "#292e42"
    border: "#414868"
```

## Partial Color Override

You can override just a few colors while keeping the rest from the base theme:

```yaml raffi.yaml
general:
  theme: dark
  theme_colors:
    accent: "#ff6b9d"  # Custom pink accent
    # All other colors use dark theme defaults
```

## Font Customization

Combine theme customization with font settings:

```yaml raffi.yaml
general:
  ui_type: native
  theme: dark
  theme_colors:
    accent: "#cba6f7"
  font_family: "Inter"
  font_size: 20
  window_width: 900
  window_height: 500
```

### Font Settings

**`font_family`** `string`

Font family name (e.g., "Inter", "Fira Sans"). System default sans-serif when omitted.


**`font_size`** `number` (default: `20`)

Base font size in pixels. Other UI sizes scale proportionally:
  - Input text: 1.2× base
  - Subtitles: 0.7× base
  - Hints: 0.6× base


**`window_width`** `number` (default: `800`)

Window width in pixels


**`window_height`** `number` (default: `600`)

Window height in pixels


**`padding`** `number`

Outer window padding in pixels. Scales with font_size if not set.


## Complete Theme Configuration

<Tabs>
<TabItem label="Dark + Catppuccin">
```yaml
general:
  ui_type: native
  theme: dark
  theme_colors:
    bg_base: "#1e1e2e"
    bg_input: "#313244"
    accent: "#cba6f7"
    accent_hover: "#89b4fa"
    text_main: "#cdd6f4"
    text_muted: "#6c7086"
    selection_bg: "#45475a"
    border: "#585b70"
  font_family: "Inter"
  font_size: 20
  window_width: 900
  window_height: 500
```
</TabItem>
<TabItem label="Light + Custom">
```yaml
general:
  ui_type: native
  theme: light
  theme_colors:
    accent: "#0066cc"
    accent_hover: "#0052a3"
  font_family: "Fira Sans"
  font_size: 18
  window_width: 800
  window_height: 600
```
</TabItem>
</Tabs>

## Theme Previews


  <details>
<summary>Default Dark Theme</summary>

    Dracula-inspired palette with:
    - Deep purple background
    - High contrast text
    - Purple/pink accents
    - Excellent readability
  </details>

  <details>
<summary>Default Light Theme</summary>

    Rose Pine Dawn palette with:
    - Soft, warm background
    - Comfortable contrast
    - Muted accents
    - Eye-friendly for bright environments
  </details>

  <details>
<summary>Custom Themes</summary>

    Create your own by:
    1. Starting with a base theme (dark or light)
    2. Overriding specific colors
    3. Testing with `raffi -u native -t [theme]`
    4. Adjusting until satisfied
  </details>

### Theme Gallery

<Image src={mainScreenshot} alt="Default dark theme with launcher and right-hand preview pane" width={800} />

<Image src={lightThemeScreenshot} alt="Built-in Rose Pine Dawn light theme" width={800} />

<Image src={catppuccinScreenshot} alt="Catppuccin Mocha custom color palette" width={800} />

<Image src={nordScreenshot} alt="Nord custom color palette" width={800} />

<Image src={gruvboxScreenshot} alt="Gruvbox Dark custom color palette" width={800} />

<Image src={solarizedScreenshot} alt="Solarized Light custom color palette" width={800} />

<Image src={tokyoNightScreenshot} alt="Tokyo Night custom color palette" width={800} />

## Color Palette Generators

Generate custom palettes using these tools:

- [Catppuccin](https://github.com/catppuccin/catppuccin)
- [Nord](https://www.nordtheme.com/)
- [Gruvbox](https://github.com/morhetz/gruvbox)
- [Tokyo Night](https://github.com/enkia/tokyo-night-vscode-theme)
- [Dracula](https://draculatheme.com/)
- [Rose Pine](https://rosepinetheme.com/)

## Troubleshooting


  <details>
<summary>Colors not applying</summary>

    1. Ensure you're using native mode: `ui_type: native`
    2. Check color format: `#RRGGBB` or `#RGB`
    3. Verify YAML syntax (proper indentation)
    4. Restart Raffi after config changes
  </details>

  <details>
<summary>Font not changing</summary>

    1. Make sure font is installed on your system
    2. Use exact font name (case-sensitive)
    3. Try `fc-list` to see available fonts
    4. Set `font_family: "Font Name"` in quotes
  </details>

  <details>
<summary>Poor contrast</summary>

    Adjust these color pairs for better readability:
    - `text_main` vs `bg_base`
    - `text_main` vs `selection_bg`
    - `accent` vs `bg_base`
  </details>