Rofi Window Switcher and Application Launcher

Rofi documentation is organized into two main tracks: Development (current/bleeding edge) and Stable (version-specific).

• Use the Development links to access the latest manpages, theme specifications, and feature guides (such as Dmenu, Script mode, and Debugging).
• Use the Stable links to access documentation specifically for the current stable release (e.g., version 2.0.0).

Key documentation areas include:

• Manpages: Detailed command-line interface and mode references.
• Themes: Specifications for rofi-theme.5 and rofi-dmenu.5.
• Guides: Specialized topics like Transparency, Positioning, Plugins, and Dynamic Themes.

Rofi supports three methods for specifying icons:

1. Filename: A direct path to an image file.
2. icon-name: A name looked up via the system's icon-theme (uses GdkPixbuf).
3. Markup String: A string rendered as an icon using Pango. This requires a <span tag to define color and font.

Markup String Example:

To use a markup string, the string must start with a <span tag. For example, to render a red power icon via dmenu:

echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu

Rofi supports three methods for specifying icons:

1. Filename: A direct path to an image file.
2. icon-name: A name looked up via the system icon theme.
3. Markup String: A string rendered as an icon using Pango. This requires a <span tag to define color and font.

For filenames and icon-names, GdkPixbuf is used for rendering.

# Example of using a markup string as an icon in dmenu mode
echo -en "testing\0icon\x1f<span color='red'>⏻</span>" | ./rofi -dmenu

The rofi window is structured as a hierarchy of boxes that pack other boxes or widgets. Boxes can be oriented either vertical or horizontal.

Default Hierarchy

The default layout follows this structure:

• window {BOX:vertical}
  • mainbox {BOX:vertical}
    • inputbar {BOX:horizontal}
      • prompt
      • entry
      • case-indicator (ci)
      • num-filtered-rows (fr)
      • num-rows (ns)
    • message
      • textbox
    • listview
      • element
        • element-icon
        • element-text
    • mode-switcher {BOX:horizontal}
      • Button (multiple)

Fixed Widgets

The following widgets are considered 'fixed' and provide core functionality:

• prompt
• entry
• overlay
• case-indicator
• message
• listview
• mode-switcher
• num-rows
• num-filtered-rows

When binding mouse actions, you can use specific button identifiers. The identifier format is Mouse<D><Button>, where D is an optional indicator for a double press.

Available Buttons

• Primary: Primary (Left) mouse button
• Secondary: Secondary (Right) mouse button
• Middle: Middle mouse button
• Forward: Forward mouse button
• Back: Back mouse button
• ExtraN: The N-th mouse button (hardware dependent)

Double Click Example

To represent a double click on the primary button, use MouseDPrimary.

Example usage in configuration:

configuration {
  me-accept-entry: "MouseDPrimary";
}

Rofi always loads a default theme. To use a different theme, add an @theme statement to your config.rasi file.

Overriding Mechanism: If you use @theme "name", you can override any property of that theme by defining the same widget section later in your config.rasi file. Multiple properties for the same widget can be grouped using commas (e.g., entry, element-text { ... }).

To inspect the default theme without your local config, run: rofi -no-config -dump-theme

Rofi themes support @media blocks to conditionally load CSS rules based on constraints like window dimensions, aspect ratio, or environment. Constraints can use integers or fractions (e.g., 120px).

Supported keys:

• min-width / max-width: Width constraints.
• min-height / max-height: Height constraints.
• min-aspect-ratio / max-aspect-ratio: Aspect ratio constraints.
• monitor-id: The monitor ID (check rofi -help for IDs).
• enabled: Boolean option. Supports environment variables or the DMENU keyword to detect if running in dmenu mode.

/* Load when width is at least 120px */
@media ( min-width: 120 px ) {
}

/* Load based on environment variable */
@media ( enabled: env(DO_LIGHT, false )) {
}

/* Load only when in dmenu mode */
@media ( enabled: DMENU) {
}

Rofi builds its window by drawing the background first, then layering each widget on top with its own transparency factor. Because transparency is applied cumulatively (one layer on top of another), setting a transparency value on every widget will result in a much less transparent final appearance than expected.

To achieve a clean transparent look, use this pattern:

1. Set all elements (*) to be fully transparent.
2. Set the background color specifically on the window element.
3. Only set background colors on specific widgets where you want distinct coloring.

/* 1. Make everything transparent by default */
* {
    background: transparent;
}

/* 2. Set the base background on the window */
window {
    background: #cc1c1c1c;
}

/* 3. Only color specific widgets as needed */