---
title: UI Modes
description: Native UI by default; legacy Fuzzel integration
---
import { Aside, Tabs, TabItem, Card, CardGrid } from '@astrojs/starlight/components';
import { Image } from 'astro:assets';
import mainScreenshot from '../../../assets/screenshots/main.png';
import keywordHelpScreenshot from '../../../assets/screenshots/keyword-help.png';
import keywordShortcutScreenshot from '../../../assets/screenshots/keyword-help-shortcuts.png';
import fuzzelScreenshot from '../../../assets/screenshots/fuzzel-mode.png';
import emojiScreenshot from '../../../assets/screenshots/emoji-picker.png';
Raffi's built-in native interface is the default and recommended UI. The external Fuzzel backend is deprecated but remains available as a legacy option for existing setups and Fuzzel-only builds.
## Overview
Raffi defaults to its native interface, with the legacy Fuzzel backend available when needed:
<div class="nav-cards">
<CardGrid>
<a href="#native-mode">
<Card title="Native Mode (Default)" icon="laptop">
Built-in graphical interface with advanced features
</Card>
</a>
<a href="#fuzzel-mode">
<Card title="Fuzzel Mode (Legacy)" icon="rocket">
Deprecated external launcher integration
</Card>
</a>
</CardGrid>
</div>
## Fuzzel Mode
Fuzzel mode uses the external [Fuzzel](https://codeberg.org/dnkl/fuzzel) launcher. It is deprecated, but remains available for existing setups and Fuzzel-only builds.
### Features
- Lightweight and fast
- Seamless Wayland integration
- Uses system Fuzzel configuration
- Minimal resource usage
### Configuration
Fuzzel appearance is configured through `~/.config/fuzzel/fuzzel.ini`:
```ini fuzzel.ini
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
```
Refer to the [Fuzzel manual](https://man.archlinux.org/man/fuzzel.ini.5.en) for full configuration details.
<Image src={fuzzelScreenshot} alt="Fuzzel dmenu mode populated by Raffi launchers" width={800} />
### Usage
<Tabs>
<TabItem label="Command Line">
```bash
raffi -u fuzzel
```
</TabItem>
<TabItem label="Config File">
```yaml
general:
ui_type: fuzzel
```
</TabItem>
</Tabs>
### Building Fuzzel-Only Binary
For a significantly smaller binary (1.1 MB vs 15 MB), you can build without the native UI:
```bash
cargo build --release --no-default-features
```
This removes the iced GUI dependency while maintaining full Fuzzel functionality.
## Native Mode
Native mode uses Raffi's built-in iced-based graphical interface with fuzzy search, keyboard navigation, and theme support. It is the default and recommended interface in standard builds.
### Features
<div class="nav-cards">
<CardGrid>
<a href="../calculator/">
<Card title="Built-in Calculator" icon="puzzle">
Evaluate mathematical expressions as you type
</Card>
</a>
<a href="../currency-converter/">
<Card title="Currency Converter" icon="patreon">
Convert between currencies with live exchange rates
</Card>
</a>
<a href="../file-browser/">
<Card title="File Browser" icon="document">
Navigate filesystem with keyboard shortcuts
</Card>
</a>
<a href="../script-filters/">
<Card title="Script Filters" icon="pencil">
Dynamic results from external commands
</Card>
</a>
<a href="../web-search/">
<Card title="Web Search" icon="magnifier">
Quick searches with URL templates
</Card>
</a>
<a href="../text-snippets/">
<Card title="Text Snippets" icon="pen">
Reusable text values with multiple sources
</Card>
</a>
<a href="../themes/">
<Card title="Theme Support" icon="moon">
Dark and light themes with color customization
</Card>
</a>
<a href="./">
<Card title="Fuzzy Search" icon="star">
Fast filtering across all entries
</Card>
</a>
</CardGrid>
</div>
<style>
{`
.nav-cards a {
text-decoration: none !important;
color: inherit;
display: flex;
height: 100%;
}
.nav-cards a article {
flex: 1;
transition: all 0.2s ease-in-out;
cursor: pointer;
display: flex;
flex-direction: column;
gap: 1rem;
border: 1px solid var(--sl-color-gray-5);
background-color: var(--sl-color-black);
}
.nav-cards a article .title {
display: flex;
flex-direction: column;
align-items: flex-start;
gap: 1rem;
font-size: 1.2rem;
}
.nav-cards a article .title .icon {
font-size: 2.5rem !important; /* Huge icons */
color: var(--sl-color-purple);
background: var(--sl-color-purple-low);
padding: 0.5rem;
border-radius: 0.5rem;
border: 1px solid var(--sl-color-purple);
}
.nav-cards a:hover article {
border-color: var(--sl-color-text-accent);
background-color: var(--sl-color-gray-6);
}
`}
</style>
### Keyboard Shortcuts
| Shortcut | Action |
| --- | --- |
| **Ctrl+J** / **Ctrl+K** | Scroll the right-hand preview pane down / up |
| **Ctrl+P** | Toggle the right-hand preview pane |
| **Ctrl+/** | Show separate keyword/action and keyboard-shortcut sections; typing filters them, and closing help restores the previous query |
| **Enter** | Launch the selected entry, or arm the selected keyword |
| **Tab** | Complete the selected keyword or file browser path |
| **Ctrl+Tab** / **Ctrl+Shift+Tab** | With `main_view` set, show one source at a time, then all of them again ([details](../../configuration/general-settings/#main-view)) |
| **Alt+P** / **Alt+N** | Previous and next search history entry |
| **Ctrl+H** | Toggle hidden files in the file browser |
| **Backspace** | In the file browser, go up to the parent directory when the input ends with `/` |
| **Escape** | Close the keyword help, or quit |
### Native Interface Screenshots
<Image src={mainScreenshot} alt="Native launcher with the right-hand preview pane" width={800} />
<Image src={keywordHelpScreenshot} alt="Keyword and keyboard shortcut help list" width={800} />
<Image src={keywordShortcutScreenshot} alt="Keyboard shortcut help filtered to Ctrl shortcuts" width={800} />
<Image src={emojiScreenshot} alt="Emoji picker with a selected glyph and Unicode metadata" width={800} />
### Usage
<Tabs>
<TabItem label="Command Line">
```bash
raffi -u native
```
</TabItem>
<TabItem label="With Initial Query">
```bash
raffi -u native -i "firefox"
```
</TabItem>
<TabItem label="Light Theme">
```bash
raffi -u native -t light
```
</TabItem>
<TabItem label="Config File">
```yaml
general:
ui_type: native
theme: dark
font_size: 20
font_family: "Inter"
window_width: 900
window_height: 500
```
</TabItem>
</Tabs>
### Window Manager Integration
<Tabs>
<TabItem label="Sway">
```ini
set $menu raffi -p
set $super Mod4
bindsym $super+Space exec cmd=$($menu) && [ -n "$cmd" ] && swaymsg exec -- "$cmd"
```
</TabItem>
<TabItem label="Hyprland">
```ini
$super = SUPER
bind = $super, R, exec, (val=$(raffi -pI); [ -n "$val" ] && hyprctl dispatch exec "$val")
```
</TabItem>
</Tabs>
## Comparison
| Feature | Legacy Fuzzel Mode | Native Mode (Default) |
|---------|--------------------|----------------------|
| **Size** | 1.1 MB (no-default-features) | 15 MB |
| **Dependencies** | Requires Fuzzel | Self-contained |
| **Calculator** | ❌ | ✅ |
| **Currency Converter** | ❌ | ✅ |
| **File Browser** | ❌ | ✅ |
| **Script Filters** | ❌ | ✅ |
| **Web Search** | ❌ | ✅ |
| **Text Snippets** | ❌ | ✅ |
| **Theme Support** | System Fuzzel config | Built-in dark/light |
| **Configuration** | `fuzzel.ini` | `raffi.yaml` |
## Automatic Selection
If no UI type is specified, Raffi selects:
1. **Native mode** in builds with the `wayland` feature (the standard build)
2. **Legacy Fuzzel mode** in Fuzzel-only builds, if `fuzzel` is available in `PATH`
<Aside type="note">
Fuzzel mode is deprecated and having Fuzzel installed does not change the default in a standard build. To use the legacy backend, select `-u fuzzel` or set `general.ui_type: fuzzel`.
</Aside>