---
title: Icons
description: Configure icon discovery, caching, and paths for Raffi entries
---
import { Aside } from '@astrojs/starlight/components';
## 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:
```yaml
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:
```json
{
"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:
```bash
raffi --refresh-cache
```
Or use the short flag:
```bash
raffi -r
```
<Aside type="note">
Refresh the cache after:
- Installing a new icon theme
- Adding custom icons to XDG directories
- Changing icon theme settings
</Aside>
## Disabling Icons
Icons can be disabled for faster startup:
### Via Command Line
```bash
raffi --no-icons
```
Or:
```bash
raffi -I
```
### Via Configuration
```yaml
general:
no_icons: true
```
<Aside type="note">
Command-line flags override configuration file settings.
</Aside>
## Examples
### Icon Name Examples
```yaml
# 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:
```yaml
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:
```bash
find /usr/share/icons -name "firefox.*"
```
2. **Refresh cache**: Icon cache may be outdated:
```bash
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:
```bash
export XDG_DATA_DIRS="$HOME/.local/share:/usr/local/share:/usr/share"
```
Then refresh the cache:
```bash
raffi --refresh-cache
```