---
title: UI Modes
description: Choose between Fuzzel integration and native interface
---
import { Aside, Tabs, TabItem, Card, CardGrid } from '@astrojs/starlight/components';
Raffi supports two distinct user interface modes, each designed for different use cases and preferences.
## Overview
Raffi can operate in two modes:
<div class="nav-cards">
<CardGrid>
<a href="#fuzzel-mode">
<Card title="Fuzzel Mode" icon="rocket">
External launcher integration with Wayland environments
</Card>
</a>
<a href="#native-mode">
<Card title="Native Mode" icon="laptop">
Built-in graphical interface with advanced features
</Card>
</a>
</CardGrid>
</div>
## Fuzzel Mode
Fuzzel mode uses the external [Fuzzel](https://codeberg.org/dnkl/fuzzel) launcher and integrates naturally with Wayland environments.
### 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.
### 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 an internal iced-based graphical interface with fuzzy search, keyboard navigation, and theme support.
### Features
<div class="nav-cards">
<CardGrid>
<a href="/features/calculator/">
<Card title="Built-in Calculator" icon="puzzle">
Evaluate mathematical expressions as you type
</Card>
</a>
<a href="/features/currency-converter/">
<Card title="Currency Converter" icon="patreon">
Convert between currencies with live exchange rates
</Card>
</a>
<a href="/features/file-browser/">
<Card title="File Browser" icon="document">
Navigate filesystem with keyboard shortcuts
</Card>
</a>
<a href="/features/script-filters/">
<Card title="Script Filters" icon="pencil">
Dynamic results from external commands
</Card>
</a>
<a href="/features/web-search/">
<Card title="Web Search" icon="magnifier">
Quick searches with URL templates
</Card>
</a>
<a href="/features/text-snippets/">
<Card title="Text Snippets" icon="pen">
Reusable text values with multiple sources
</Card>
</a>
<a href="/features/themes/">
<Card title="Theme Support" icon="moon">
Dark and light themes with color customization
</Card>
</a>
<a href="/features/ui-modes/">
<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>
### 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 | Fuzzel Mode | Native Mode |
|---------|-------------|-------------|
| **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 automatically chooses:
1. **Fuzzel mode** if `fuzzel` binary is found in PATH
2. **Native mode** as fallback (if built with `wayland` feature)
<Aside type="note">
The `wayland` feature must be enabled at compile time for native mode support.
</Aside>