Learn Zellij - Status Bar, Tab Bar & Theme Customization

#Introduction

Welcome to episode 11 of the Learn Zellij series! The last two episodes shaped the way you operate Zellij: personal keybindings in episode 9, and deterministic layouts in episode 10. Now comes the most visible part: Status Bar, Tab Bar, and Theme Customization. This isn't just cosmetics — a comfortable-to-read interface determines how fast your eyes find information among ten panes.

There are four areas you'll master: (1) Zellij's built-in UI plugins — tab-bar, status-bar, and compact-bar — and how to configure them, (2) the keybinding tooltip on compact-bar that arrived in 0.43, (3) the latest theme spec from 0.42 with well-defined UI components, and (4) built-in themes, custom themes in ~/.config/zellij/themes/, and the theme_dark/theme_light dark-light auto-switching from 0.44.

Why does this chapter matter? Most of Zellij's beauty — and most of a beginner's confusion — comes from the UI lines at the top and bottom of the screen. The tab bar tells you which tab you're on, the status bar whispers available keybindings, and the theme keeps all of it consistent with your editor and terminal. Mastering this part means an informative workspace without noise.

One delightful thing about Zellij's interface: almost all its changes are live. Configuration is continuously watched by Zellij, so changing a theme or adding a tooltip shows up instantly without a session restart. This makes experimentation very cheap — you can change colors dozens of times until you find the right combination without ever leaving the workspace. By the end of this episode, you'll have an informative, tidy, consistent interface, ready to move on to episode 12 about options and environment. Let's begin.

#UI Plugins: tab-bar, status-bar, and compact-bar

Zellij's interface isn't part of the main server — it consists of plugins loaded through the plugins block in config.kdl. This is an important design to understand: every UI element can be replaced, customized, or even disabled. The three plugins you'll most often see are tab-bar (default at top), status-bar (default at bottom), and compact-bar — a minimal variant showing only the session name, active mode, and tabs.

plugins {
    tab-bar location="zellij:tab-bar"
    status-bar location="zellij:status-bar"
    compact-bar location="zellij:compact-bar"
}

Note that the location attribute on this block points to the plugin source — built-in aliases like zellij:tab-bar — not the on-screen position. The tab bar displays itself at the top and the status bar at the bottom as each plugin's built-in behavior. Since 0.41, the status bar was redesigned into a more compact single line that's aware of the keybinding preset: it guides you through key chords like Ctrl p then ?, and shows a floating pane indicator. For the old-style status bar, run Zellij with the classic layout.

#Hiding and Replacing the UI Layout

Not everyone needs a full status bar at all times. Zellij provides several built-in layouts for controlling how much UI is shown, all selectable via the --layout flag or the default_layout option.

zellij --layout disable-status-bar

zellij --layout compact

zellij --layout classic

The compact layout loads compact-bar — a thin line at the bottom showing the session name, active mode, and open tabs. The disable-status-bar layout removes the status bar entirely, giving all screen pixels to the panes. The classic layout restores the old two-line status bar. You can set one of them as the default via the default_layout option, or load it per-session. For more granular display control, combine it with global options like simplified_ui true, which asks plugins to render UI without arrow glyphs — useful when a Nerd Font isn't available.

All these UI layouts can still be combined with themes and other options. The compact layout, for example, still respects the theme you choose — the 0.42 theme spec applies to every plugin drawn, whatever bar is used. For finer control, global options like simplified_ui true ask plugins to render UI without decorative glyphs (including arrows), and the hide_session_name option hides the session name from the tab bar display. By choosing the right layout and combining it with display options, you can make the interface as thin as possible without losing important information.

#Keybinding Tooltips on compact-bar (0.43)

One of the most common complaints about Zellij: the status bar always showing keybinding hints takes up space. 0.43 answers this with tooltips for compact-bar — hints no longer always show, but appear when needed. By default the tooltip appears automatically when you enter a non-base mode (for example Pane or Tab mode), then disappears. You can also trigger it manually with a single keybinding.

plugins {
    compact-bar location="zellij:compact-bar" {
        tooltip "F1"
    }
}

With the configuration above, pressing F1 brings up keybinding hints at any time, and hints automatically appear when the mode changes. This gives you the best of both worlds: a clean screen while working, and help always one keystroke away. For those using the full status bar, tooltip configuration isn't relevant — the status bar already displays hints permanently.

#The New Theme Spec (0.42)

Starting with version 0.42, Zellij introduced a new theme definition spec that's far more expressive than a simple color mapping. Instead of defining a dozen colors and hoping the UI uses them correctly, themes are now defined by UI components — the elements plugins actually draw. Each component receives six colors: base, background, and four emphasis_0 through emphasis_3.

themes {
    arman-night {
        text_unselected {
            base 200 200 200
            background 20 22 30
            emphasis_0 255 255 255
            emphasis_1 160 160 160
            emphasis_2 120 120 120
            emphasis_3 90 90 90
        }
        ribbon_selected {
            base 30 30 46
            background 137 180 250
            emphasis_0 255 255 255
            emphasis_1 200 200 200
            emphasis_2 150 150 150
            emphasis_3 100 100 100
        }
    }
}

The core components you need to know: text_unselected and text_selected for regular text (including the modifier indicator in the status bar), ribbon_unselected and ribbon_selected for tabs and mode pills, frame_selected and frame_unselected for pane borders, and table_* and list_* for list widgets like the session-manager. Colors can be written as u8 true-color triples (the example above), hex strings like "#16161D", or a single u8 for 256 colors. One rule you must remember: if one component is declared, all its colors must be complete — partial declarations are rejected by Zellij at startup.

#Built-in Themes and Custom Themes

Zellij bundles dozens of built-in themes usable without any extra configuration. The two most popular in the community are dracula and catppuccin — including catppuccin-latte for the light variant. Select one with the theme option at the root of config.kdl:

theme "dracula"
theme "catppuccin"

For custom themes, you have two options: define the themes block directly in config.kdl (the fastest way to iterate since it reloads live), or store one file per theme in the ~/.config/zellij/themes/ directory — the exact location can be checked with zellij setup --check. Every file in that directory automatically becomes available as a theme, complete with its own themes node. To apply a theme without touching the config, use zellij options --theme dracula when starting a session.

The most practical way to create a custom theme is to start from a finished definition. Run zellij setup --dump-config and copy an existing themes block as a starting point, or open one of the files in the themes directory to see a complete component pattern. Because config reloads live, put a trial theme directly in config.kdl for fast iteration — change colors, save, see the result instantly. Once it feels right, move the definition to a separate file in ~/.config/zellij/themes/ so the main config stays lean and themes are easy to move between machines via dotfiles. Remember the theme spec's golden rule: one declared component means all its colors must be complete, so copy the whole declaration then change one at a time.

#Dark-Light Theme Auto-Switching (0.44)

The most interesting feature for visual consistency comes from 0.44: theme auto-switching based on dark/light mode. Zellij supports the CSI 2031 protocol — modern terminals send a signal when the OS switches between dark and light themes, and Zellij relays it. With two new options, you can assign a theme for each condition:

theme "dracula"
theme_dark "dracula"
theme_light "catppuccin-latte"

When the terminal reports dark mode, Zellij uses theme_dark; when light, theme_light takes over. The theme option still applies as the base theme for cases without a signal. For terminals that don't yet support CSI 2031, Zellij provides manual control: zellij action toggle-theme, zellij action set-dark-theme, and zellij action set-light-theme — while also forwarding instructions to applications inside panes that ask for them.

Keep in mind that auto-switching only means something if the terminal actually sends a theme signal; without it, theme_dark and theme_light are only used through manual actions. Also make sure both themes actually exist among the built-in themes or in the themes directory, and that a Nerd Font is installed — without a Nerd Font, theme indicators and glyphs won't render well whatever theme you choose. With all those conditions met, your Zellij will follow the system's dark-light mode automatically, in sync with your editor and terminal.

#Common Pitfalls

1. Incomplete theme component declarations. Writing text_unselected without emphasis_2 makes Zellij reject the config. Fix: complete all six colors, or remove the component to use the default.
2. Storing theme files in the wrong directory. Themes in unrecognized locations won't appear in the list. Fix: put them in ~/.config/zellij/themes/ and verify with zellij setup --check.
3. Misunderstanding location on the plugins block. location is the plugin source, not its position on screen. To hide a bar, remove its line or use layouts like compact and disable-status-bar.
4. Relying on auto-switching without terminal support. If the terminal doesn't send a theme signal, theme_dark/theme_light won't trigger. Fix: use zellij action toggle-theme for manual control.
5. Switching themes but forgetting the Nerd Font. A beautiful theme still renders broken if icon glyphs aren't supported by the font. Fix: make sure a Nerd Font is installed and set as the terminal font, as prepared in episode 0.

#Closing

In this episode 11 you've overhauled Zellij's appearance from top to bottom: getting to know the tab-bar, status-bar, and compact-bar UI plugins along with the plugins block, configuring the keybinding tooltip on compact-bar from 0.43, understanding the component-based 0.42 theme spec, choosing built-in themes like dracula and catppuccin, creating custom themes in ~/.config/zellij/themes/, and using the theme_dark/theme_light auto-switching from 0.44.

Key takeaways:

• Zellij's UI is plugins — replaceable, customizable, and hideable.
• compact-bar + tooltips = a clean screen with help one keystroke away.
• The 0.42 theme spec is component-based; declarations must be complete.
• Custom themes are stored per file in ~/.config/zellij/themes/.
• Dark-light auto-switching needs a terminal that sends a theme signal.

Your interface is now not only comfortable to use, but also consistent with your editor ecosystem. In episode 12 next, we align the core behavior: Options & Environment Management — mouse_mode, scroll_buffer_size, copy_command, default_mode, default_layout, session_serialization, up to managing per-pane environments and working directories. See you in episode 12!