---
title: General Settings
description: Configure Raffi's UI, theme, fonts, and window properties
---
import { Aside } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import mainScreenshot from '../../../assets/screenshots/main.png';
import fallbacksScreenshot from '../../../assets/screenshots/fallbacks.png';
import mainSearchScreenshot from '../../../assets/screenshots/main-search.png';
import mainRecentScreenshot from '../../../assets/screenshots/main-recent.png';
import mainSourceScreenshot from '../../../assets/screenshots/main-source.png';
## Overview
The `general` section in your configuration file sets persistent defaults for Raffi's appearance and behavior. Command-line flags override config values when a setting has a corresponding flag.
<Aside type="note">
Command-line flags always override settings from the configuration file.
</Aside>
## Configuration Options
All fields in the `general` section are optional.
**`ui_type`** `string` (default: `native` in standard builds; `fuzzel` in Fuzzel-only builds)
Select the UI backend. The native interface is the default and recommended option
in standard builds; Fuzzel is a deprecated legacy backend. Valid options:
- `native` - Uses built-in iced-based GUI (default in standard builds)
- `fuzzel` - Uses the deprecated external Fuzzel launcher
Equivalent to `-u` or `--ui-type` flag.
**`theme`** `string` (default: `dark`)
Color theme for the native interface. Valid options:
- `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
Equivalent to `-t` or `--theme` flag. Only applies to native UI.
**`no_icons`** `boolean` (default: `false`)
Disables icon loading for faster startup.
Equivalent to `-I` or `--no-icons` flag.
**`renderer`** `string` (default: `cpu`)
How the native UI draws its window. Valid options:
- `cpu` - Software rendering (default). Skips GPU driver setup, so the window opens sooner.
- `gpu` - Vulkan/OpenGL rendering through wgpu.
An `ICED_BACKEND` environment variable (`tiny-skia` or `wgpu`) takes precedence. See [Startup performance](#startup-performance).
**`show_preview`** `boolean` (default: `false` for launchers, automatic for addons)
Controls the Alfred-style right-hand preview and details pane in the native UI.
Addon results (text snippets, file browser, script filters, emoji, calculator, currency, web searches) always show a preview. Plain launcher entries only show one when this is `true`, or when the entry itself sets `show_preview: true`. Press **Ctrl+P** to toggle the pane at runtime; when nothing is shown for a launcher, the first press turns launcher previews on.
## Preview Pane
**`preview`** `object`
Appearance of the right-hand preview pane. All fields are optional.
**`preview.font_size`** `number` (default: `16`)
Base text size in pixels. The title (1.4×), headings (0.8×), hero values (2.2×) and emoji glyphs (5×) scale from it.
**`preview.font_family`** `string`
Font family for the pane. Defaults to the UI font (`font_family`).
**`preview.mono_font_family`** `string`
Font family for code and text blocks (snippet content, scripts, file contents). Defaults to the system monospace font.
**`preview.width_percent`** `number` (default: `50`)
Share of the window width given to the pane, clamped to 10–80.
**`preview.colors`** `object`
Hex colour overrides (`#RGB`, `#RRGGBB`, or `#RRGGBBAA`). Unset colours come from the theme.
- `bg` - pane background
- `bg_block` - background of content blocks
- `text_main` - title and body text
- `text_muted` - subtitles, metadata keys
- `accent` - headings, badges, hero values
- `border` - pane and block borders
```yaml
general:
show_preview: true
preview:
font_size: 18
mono_font_family: "JetBrains Mono"
width_percent: 55
colors:
accent: "#cba6f7"
bg_block: "#1e1e2e"
```
<Image src={mainScreenshot} alt="Native launcher showing a standard entry in the preview pane" width={800} />
**`default_script_shell`** `string` (default: `bash`)
Default interpreter for inline scripts. Common values:
- `bash` (default)
- `/bin/zsh`
- `python3`
Equivalent to `--default-script-shell` flag.
**`max_history`** `number` (default: `10`)
Maximum number of search query history entries.
Set to `0` to disable history. Navigate history with Alt+P (previous) and Alt+N (next) in native mode.
<a id="sort_mode"></a>
**`sort_mode`** `string` (default: `hybrid`)
Controls how launcher entries, [text snippets](../../features/text-snippets/#snippet-keywords-and-search), [password store](../../features/password-store/) entries and [Bitwarden](../../features/bitwarden/) logins are ordered by past use. With no search query they are listed in this order; while typing, it breaks ties between equally good matches. Valid options:
- `frequency` - Sort by launch count (most frequently used first)
- `recency` - Sort by last-used time (most recently used first)
- `hybrid` - Combined score: 40% frequency + 60% recency (default)
Launchers you have never used, or that tie, keep the order they have in your config file.
The MRU cache at `~/.cache/raffi/mru.cache` stores both launch counts and timestamps. Existing caches using the old format are migrated automatically on next use. Snippet use is kept separately in `~/.cache/raffi/snippets.cache`, and password entry use in `~/.cache/raffi/vault.cache`.
**`clipboard_history`** `string` (default: `auto`)
Clipboard manager used by `{clipboard:N}` in [text snippets](../../features/text-snippets/#clipboard-history). Valid options:
- `auto` - Use the running one, preferring cliphist, then CopyQ, then clipman (default)
- `cliphist` - Always use cliphist
- `copyq` - Always use CopyQ
- `clipman` - Always use clipman
- `none` - Turn clipboard history off
`{clipboard}` reads the current clipboard with `wl-paste`, `xclip` or `xsel` and does not depend on this setting.
**`terminal_classes`** `list of strings` (default: `[]`)
Extra window classes that the [`hypr_paste`](../../features/text-snippets/#default-actions) snippet action treats as terminals. Terminals get Ctrl+Shift+V instead of Ctrl+V. The list is added to the built-in one, which covers Alacritty, foot, kitty, Ghostty, WezTerm, GNOME Terminal, GNOME Console, Ptyxis, Konsole, Tilix, Terminator, Xfce Terminal, Rio and st. Classes are matched case-insensitively. Run `hyprctl activewindow` in your terminal to find its class.
```yaml
general:
terminal_classes:
- my-terminal
```
## Fallbacks
**`fallbacks`** `list of strings` (default: `[]`)
Addon entries that appear at the bottom of the launcher list when you type a non-empty query. This is useful for search-type addons (web searches, script filters) so they are always accessible without remembering their keywords.
Each entry is a dot-separated path: `addons.<type>."<name>"` where `<type>` is `web_searches` or `script_filters`, and `<name>` matches the addon's `name` field. `addons.terminal` takes no name and adds a row that runs the query in a terminal, see [Run in Terminal](../../features/terminal/).
Behavior:
- Only shown when the search query is **non-empty**
- **Not shown** when already in an addon mode (script filter, web search, file browser, etc.)
- **Web search** fallbacks open the URL with the current query and exit
- **Script filter** fallbacks switch the input to that filter's keyword mode
- The **terminal** fallback runs the query as a shell command in a terminal and exits
```yaml
general:
fallbacks:
- addons.web_searches."Google"
- addons.web_searches."DuckDuckGo"
- addons.script_filters."Search Google"
- addons.terminal
```
<Aside type="tip">
Fallbacks work best with search-type addons. The referenced addon must be defined in your `addons` section.
</Aside>
<Image src={fallbacksScreenshot} alt="Configured fallback search entries and selected URL preview" width={800} />
## Main view
<Image src={mainSearchScreenshot} alt="One search listing a configured launcher and matching demo windows, identified by their source badges" width={800} />
<Image src={mainRecentScreenshot} alt="An empty query showing configured launchers and a recently picked demo checklist snippet" width={800} />
<Image src={mainSourceScreenshot} alt="The same search narrowed to Launchers with Ctrl+Tab, as shown in the footer" width={800} />
**`main_view`** `list of strings` (default: unset)
Mixes addon results into the main list, so typing `gmail` shows the matching browser tabs without typing the `tabs` trigger first. Native UI only.
Accepted entries:
- `launchers`: your launcher entries
- `browser_tabs`, `windows`, `system`, `media`, `audio`, `bluetooth`, `pass`
- `text_snippets.<name>` and `script_filters.<name>`, where `<name>` is the source's `name` field. The `addons.<type>."<name>"` form used by `fallbacks` works too.
When `main_view` is unset, the main list shows launchers only, as before. When it is set, only the listed sources appear, so keep `launchers` in the list if you still want your launchers.
Results are grouped by source in the order you list them, and each addon row carries a small badge naming where it comes from. Each addon adds at most 5 rows, ranked the same way as in its own mode, except that an addon row only shows when every word you typed appears in it, so typing `brave` does not bring up a tab whose title merely has those letters scattered through it. A tab for the site a pasted URL names, and a snippet whose keyword starts with your query, still show. Script filters do their own matching and are left alone.
When a group has a row whose title starts with what you typed, or has a word that does, that group moves ahead of the groups that only match elsewhere. Typing `brave` lists your Brave Browser launcher before tabs and snippets that only mention Brave in their text, even when `browser_tabs` comes first in `main_view`. Groups keep the order you listed them in otherwise.
With an empty query, the main list shows your launchers plus the 5 things you picked most recently from `browser_tabs`, `windows`, `pass`, text snippet sources and script filters. Each one sits with its source, at the same place its typed results would, newest first. A tab or window that has been closed since is left out and the next older pick takes its place, and so are windows picked before you last logged in. A tab is found again by its address after a browser restart. Picks count from both the main list and the addon's own mode, but only for sources listed in `main_view`; closing a tab with Ctrl+Enter is not a pick. Rows from `system`, `media`, `audio` and `bluetooth` only appear once you type.
Recent picks are kept in `~/.cache/raffi/recent.cache` (readable only by you). It holds tab addresses, password entry names, and the arguments and variables of script filter rows, so avoid listing a script filter whose variables carry secrets, and delete the file if you would rather not keep that history.
Pressing Enter on an addon row switches to that addon's mode with your query (the input becomes `tabs gmail`, for instance) and runs the row there. Confirmations, lists that stay open after an action, and usage ranking behave exactly as in the addon's own mode.
Addon data loads in the background when Raffi starts. Sources that cannot run here (no supported compositor, a missing tool, no connected browser) are skipped quietly. Unknown or disabled entries print a warning at startup.
Script filters run each time you pause typing, so set their `min_query_length` to avoid running them for one or two characters. A filter runs once at a time here, and a run that takes longer than 10 seconds is stopped. Keep in mind that a listed filter receives everything you type in the main list, so avoid listing one that sends its query to a remote service you would not search with otherwise. Dynamic previews are only shown in the filter's own mode.
```yaml
general:
main_view:
- launchers
- browser_tabs
- windows
- text_snippets."Emails"
- script_filters."GitHub Issues"
```
Typing a trigger (`tabs gmail`) still opens the addon's full list, and fallbacks still show below the main list.
Ctrl+Tab narrows the main list to one source at a time, in the order of `main_view`, and comes back to all of them after the last one. Ctrl+Shift+Tab goes the other way. The footer shows which one is current, for instance `Ctrl+Tab Tabs` or `Ctrl+Tab All`. A single source lists all of its matches with no 5-row limit, and shows its rows before you type anything, except script filters, which still need a query. Fallbacks, keyword suggestions and inline results such as the calculator only show when all sources are listed. The choice stays while you type and lasts until Raffi closes.
## Font and Typography
**`font_size`** `number` (default: `20`)
Base font size in pixels. Other UI elements scale proportionally:
- Input text: 1.2× base size (24px by default)
- Item descriptions: 1.0× base size (20px by default)
- Subtitles: 0.7× base size (14px by default)
- Hints: 0.6× base size (12px by default)
**`font_family`** `string`
Font family name (e.g., `"Inter"`, `"Fira Sans"`, `"Roboto"`).
When omitted, the system default sans-serif font is used.
## Window Dimensions
**`window_width`** `number` (default: `800`)
Launcher window width in pixels (native mode only).
**`window_height`** `number` (default: `600`)
Launcher window height in pixels (native mode only).
**`padding`** `number` (default: `20`)
Outer window padding in pixels.
When not set, padding scales automatically with `font_size`.
## Theme Colors
Customize individual theme colors under the `theme_colors` section. Each field accepts hex color strings in the format `#RGB`, `#RRGGBB`, or `#RRGGBBAA`.
Only specified colors are overridden; the rest come from the base theme selected via `theme`.
**`theme_colors.bg_base`** `string`
Base background color.
**`theme_colors.bg_input`** `string`
Input field background color.
**`theme_colors.accent`** `string`
Primary accent color (used for highlights and selected items).
**`theme_colors.accent_hover`** `string`
Accent color for hover states.
**`theme_colors.text_main`** `string`
Primary text color.
**`theme_colors.text_muted`** `string`
Muted/secondary text color.
**`theme_colors.selection_bg`** `string`
Background color for selected items.
**`theme_colors.border`** `string`
Border color.
## Startup performance
To see where startup time goes, run `raffi -d /tmp/raffi.log` and look for
the `startup:` lines (milliseconds since Raffi started).
Large or SVG launcher icons are converted to small PNG copies in
`~/.cache/raffi/icon-thumbnails` on first use, so later launches skip decoding
them. `raffi --refresh-cache` clears these copies along with the icon cache.
If you use `renderer: gpu`, Vulkan layers installed by other programs (Steam,
for example) are loaded on every launch. Setting `VK_LOADER_LAYERS_DISABLE=all`
in Raffi's environment skips them.
## Example Configurations
### Native UI with Light Theme
```yaml
general:
ui_type: native
theme: light
font_size: 18
font_family: "Inter"
window_width: 900
window_height: 500
```
### Custom Theme Colors (Catppuccin Mocha)
```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"
```
### Minimal Fuzzel Configuration
```yaml
general:
ui_type: fuzzel
no_icons: true
default_script_shell: /bin/zsh
```
## Command-Line Override
The following general settings can be overridden with command-line flags.
`window_width`, `window_height`, `clipboard_history`, and `terminal_classes` have no flag and can only be set in the configuration file.
```bash
# Override UI type
raffi --ui-type native
# Override theme
raffi --theme light
# Disable icons
raffi --no-icons
# Set custom script shell
raffi --default-script-shell /bin/zsh
```