Icons

Overview

Raffi supports icons from system icon themes. Icons are automatically discovered from standard XDG directories and cached for performance.

Icon Specification

Specify icons by their theme name:

launchers:
  firefox:
    binary: firefox
    description: "Firefox"
    icon: firefox

Raffi searches for icons in system icon directories and uses the icon name to look up the full path.

Icon Discovery

Raffi discovers icons from standard XDG directories:

• $XDG_DATA_HOME/icons (defaults to ~/.local/share/icons)
• $XDG_DATA_DIRS/icons (defaults to /usr/local/share/icons:/usr/share/icons)
• $XDG_DATA_HOME/pixmaps
• $XDG_DATA_DIRS/pixmaps

Supported Formats

Raffi supports:

• PNG images (.png)
• SVG images (.svg)

Icon Size Preference

Raffi renders icons at 48×48 pixels and prefers larger source icons for better quality:

1. Scalable icons (from scalable/ directories) are prioritized
2. 48×48 or larger icons are preferred over smaller sizes
3. If multiple sizes exist, the largest icon is selected

For example, given these icon paths:

/usr/share/icons/Papirus/16x16/apps/firefox.png
/usr/share/icons/Papirus/48x48/apps/firefox.png
/usr/share/icons/Papirus/scalable/apps/firefox.svg

Raffi selects the scalable SVG for best quality.

Icon Caching

Icon paths are cached to improve startup performance.

Cache Location

$XDG_CACHE_HOME/raffi/icon.cache

Defaults to ~/.cache/raffi/icon.cache if XDG_CACHE_HOME is not set.

Cache Format

The cache is a JSON file mapping icon names to absolute paths:

{
  "firefox": "/usr/share/icons/Papirus/scalable/apps/firefox.svg",
  "terminal": "/usr/share/icons/Papirus/48x48/apps/terminal.png",
  "chromium": "/usr/share/icons/hicolor/scalable/apps/chromium.svg"
}

Refreshing the Cache

The cache is automatically generated on first run. To regenerate it:

raffi --refresh-cache

Or use the short flag:

raffi -r

Note

Refresh the cache after:

• Installing a new icon theme
• Adding custom icons to XDG directories
• Changing icon theme settings

Disabling Icons

Icons can be disabled for faster startup:

Via Command Line

raffi --no-icons

Or:

raffi -I

Via Configuration

general:
  no_icons: true

Note

Command-line flags override configuration file settings.

Examples

Icon Name Examples

# System icon by name
launchers:
  firefox:
    binary: firefox
    description: "Firefox"
    icon: firefox

  # No icon specified
  terminal:
    binary: kitty
    description: "Terminal"

Real-World Examples

From the example configuration:

launchers:
  wally:
    binary: jumpapp
    args: ["-X", "wally"]
    description: "Wally"
    icon: wally
    ifexist: wally

  evolution-mail:
    binary: jumpapp
    args: ["-t", "Evolution", "-X", "evolution"]
    description: "Evolution Mail"
    icon: evolution-mail
    ifexist: evolution

  signal:
    binary: jumpapp
    args: ["-X", "signal", "signal-desktop"]
    description: "Signal"
    icon: signal-desktop
    ifexist: signal-desktop

  golang:
    binary: jumpapp
    args: ["-c", "jetbrains-goland", "goland"]
    description: "Goland"
    icon: goland

Troubleshooting

Icon Not Found

If an icon isn’t displaying:

1. Check icon name: Verify the icon exists in your theme:

   find /usr/share/icons -name "firefox.*"

2. Refresh cache: Icon cache may be outdated:

   raffi --refresh-cache

3. Add to XDG directories: Place your icon in a standard XDG icon directory so it can be found by name.

Custom Icon Directories

To use icons from custom directories, add them to XDG environment variables:

export XDG_DATA_DIRS="$HOME/.local/share:/usr/local/share:/usr/share"

Then refresh the cache:

raffi --refresh-cache