Fuzzel

Raffi can hand its list of entries to Fuzzel and let Fuzzel draw the menu. This is a legacy option kept for setups that already rely on it. Fuzzel shows your apps and entries with their icons and descriptions, and Raffi runs whatever you pick.

Turning it on

Command line

raffi -u fuzzel

raffi.yaml

general:
  ui_type: fuzzel

Fuzzel needs to be installed and in your PATH:

# Arch Linux
sudo pacman -S fuzzel

# Debian and Ubuntu
sudo apt install fuzzel

# Fedora
sudo dnf install fuzzel

What you lose

Fuzzel only shows a flat list, so everything that needs Raffi’s own window is left out:

• the addons (calculator, file browser, clipboard history, passwords, Slack and the rest)
• the preview pane, keyword help and keyboard shortcuts
• themes, opacity and font settings from raffi.yaml
• main_view and fallbacks, which Raffi ignores with a warning
• entries that use alias, which are hidden

Which one starts by default

The standard build always opens Raffi’s own window, even when Fuzzel is installed. Fuzzel is used only when you ask for it, or when you run a Fuzzel-only build.

Fuzzel-only builds

If Fuzzel is all you need, you can use a much smaller binary that leaves out Raffi’s window and its addons. Linux x86_64 releases include one as raffi-fuzzel-only_<version>_Linux_x86_64.tar.gz. To build it yourself:

cargo build --release --no-default-features

This build starts Fuzzel by default. It stops with an error when Fuzzel is missing, or when your config sets main_view or fallbacks, since Fuzzel can’t show them. Pass -u fuzzel or set ui_type: fuzzel to start it anyway and ignore those settings. The build also skips config checking: --check-config is unavailable and unknown keys in your config produce no warning. Add --features config-validation to the build command to keep the checks.

A minimal raffi.yaml for Fuzzel:

general:
  ui_type: fuzzel
  no_icons: true

Styling Fuzzel

Fuzzel reads its look from ~/.config/fuzzel/fuzzel.ini, and Raffi’s theme settings have no effect on it. The fuzzel.ini manual lists every option. This example works well with Raffi:

dpi-aware=yes
font=RobotoMonoNerdFont-Thin:size=16
terminal=kitty
width=50
layer=overlay
exit-on-keyboard-focus-loss=no
inner-pad=15
fields=filename,name

[colors]
background=282a36ff
text=f8f8f2ff
match=8be9fdff
selection-match=8be9fdff
selection=44475add
selection-text=f8f8f2ff
border=bd93f9ff

Option	Effect	Example
dpi-aware	Scale with the screen’s DPI	yes or no
font	Font family and size	RobotoMonoNerdFont-Thin:size=16
terminal	Terminal for entries that run in one	kitty, alacritty, foot
width	Width in characters	50
layer	Wayland layer to draw on	overlay, top
exit-on-keyboard-focus-loss	Close when another window takes focus	yes or no
inner-pad	Padding inside the window, in pixels	15
fields	Fields that searching matches	filename,name

Colors go in the [colors] section as 8-digit hex values (RRGGBBAA):

Option	Colors
background	Window background
text	Text
match	Matched characters
selection	Selected row background
selection-text	Selected row text
selection-match	Matched characters in the selected row
border	Window border

Color schemes

The example above uses Dracula. Swap in one of these [colors] sections for another look.

Catppuccin Mocha

[colors]
background=1e1e2eff
text=cdd6f4ff
match=89b4faff
selection=45475aff
selection-text=cdd6f4ff
selection-match=89dcebff
border=b4befeff

Nord

[colors]
background=2e3440ff
text=eceff4ff
match=88c0d0ff
selection=434c5eff
selection-text=eceff4ff
selection-match=8fbcbbff
border=5e81acff

Gruvbox Dark

[colors]
background=282828ff
text=ebdbb2ff
match=fabd2fff
selection=3c3836ff
selection-text=fbf1c7ff
selection-match=fe8019ff
border=d65d0eff

Tip

layer=overlay keeps Fuzzel above fullscreen windows, and exit-on-keyboard-focus-loss=no keeps it open when it loses focus. Add comment to fields if you also want to search desktop file comments.