Icons

Overview

Raffi supports icons from system icon themes. Icons are automatically discovered from standard XDG directories and cached for performance. When an entry does not resolve an icon directly, Raffi now tries to infer one from installed .desktop files and finally falls back to a bundled generic icon.

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.

If icon is omitted, Raffi first tries likely launcher candidates such as the configured binary name and non-option arguments. This helps wrapper launchers still pick up a matching system icon.

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:

Scalable icons (from scalable/ directories) are prioritized
48×48 or larger icons are preferred over smaller sizes
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.

Automatic Fallbacks

When a launcher icon is missing, Raffi resolves icons in this order:

Explicit icon path or theme icon name from the launcher config
Binary name or other likely launcher arguments
Matching Icon= metadata from installed XDG .desktop files
Bundled generic fallback icon

This means entries without an icon: field should still display a reasonable system icon when Raffi can infer one.

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

Disabling Icons

Icons can be disabled for faster startup:

Via Command Line

raffi --no-icons

Or:

raffi -I

Via Configuration

general:
  no_icons: true

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:

Check icon name: Verify the icon exists in your theme:
Terminal window
```
find /usr/share/icons -name "firefox.*"
```
Refresh cache: Icon cache may be outdated:
Terminal window
```
raffi --refresh-cache
```
Add to XDG directories: Place your icon in a standard XDG icon directory so it can be found by name.
Check desktop metadata: For wrapper commands, ensure the target application has a valid .desktop file with an Icon= entry.

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