feat: customizable key format, colors, aliases, and compact display

[AdamsGH]

Summary

Adds comprehensive customization options to zjstatus-hints, addressing
the long-standing requests for compact display (#12) and custom
styling (#5).

New configuration options

Option	Description
modifier_style	Key display style: "long" / "short" / "symbol" (^n, M-h)
hint_format	Per-hint template with {key} and {action} variables
separator	Delimiter between hints (e.g. " · ")
max_keys	Limit alternative keybindings per action
alias_{label}	Rename action labels (e.g. alias_fullscreen "full")
key_alias_{key}	Rename bare keys (e.g. key_alias_enter "⏎")
key_fg/bg, label_fg/bg	Global color overrides (#RRGGBB)
{label}_key_fg	Per-label color overrides
{mode}.{label}_key_fg	Per-mode per-label color overrides

Before / After

Default (unchanged):

n new x close f fullscreen w float r split right d split down ←→ move ENTER select

With compact config (modifier_style "symbol", separator "·", aliases, max_keys "4"):

n new · x close · f full · w float · r S→ · d S↓ · ←→ move · ⏎ sel

One more example, default & using by me for a few weeks

  PANE  1                                    n|Alt n  new   x  close   f  fullscreen   w|Alt f  float   e  embed   r  split right   d  split down   c  rename   h|←|Alt j|j|↓|Alt ↓|Alt k|↑|Alt ↑|k|→|l  move   ENTER  select   04 Mar 09:19  <- oroginal
  PANE  1                                                                                                                      n  new    x  close    f  full    w  float    e  embed    r  S→    d  S↓    ←→  move    ⏎  sel   04 Mar 09:47   <- custom 

Backward compatibility

All new options have defaults that preserve existing behavior.
Zero-config installations produce identical output to the previous version.

Closes #5, closes #12 - hope this would be useful for someone else.
Thanks for this extension, mate - idk how'd I live without it with my bad memory - very useful stuff =)

[AdamsGH]

Configuration examples

Every example below is independent — pick what you need, ignore the rest.

Example 1: Just make keys shorter

The simplest change. Turns Ctrl + n into ^n and Alt + h into M-h:

zjstatus-hints location="..." {
    modifier_style "symbol"
}

Before: Ctrl + p pane Ctrl + t tab Ctrl + n resize After: ^p pane ^t tab ^n resize

If you prefer C-n / A-h notation instead, use "short".

Example 2: Add separators between hints

By default hints are glued together. A separator makes them easier to read:

zjstatus-hints location="..." {
    separator " · "
}

Before: n new x close f fullscreen After: n new · x close · f fullscreen

Other ideas: " | ", " ⋅ ", " " (just a space for subtle spacing).

Example 3: Too many keys per action? Limit them

Zellij merges shared_except keybindings into every mode. This often means a single action shows 6–8 alternative keys. max_keys trims it:

zjstatus-hints location="..." {
    max_keys "4"
}

Before: Alt =|Alt +|=|+|Alt -|- resize ←|h|j|↓|↑|k|→|l increase After: Alt =|Alt +|=|+ resize ←|h|j|↓ increase

Set to "2" or even "1" for maximum compactness.

Example 4: Rename long action labels

Some labels like split right, fullscreen, half page eat up space. Rename them with alias_ options (use underscores for spaces):

zjstatus-hints location="..." {
    alias_fullscreen  "full"
    alias_split_right "S→"
    alias_split_down  "S↓"
    alias_rename      "ren"
    alias_half_page   "½pg"
    alias_select      "sel"
}

Before: r split right d split down f fullscreen ENTER select After: r S→ d S↓ f full ENTER sel

You can alias any label that appears in the bar. Common ones: new, close, fullscreen, float, embed, split right, split down, rename, move, select, resize, increase, decrease, scroll, page, half page, search, edit, detach, manager, config, plugins, about, break pane, sync.

Example 5: Replace special key names with symbols

ENTER, SPACE, ESC etc. can be replaced with Unicode symbols:

zjstatus-hints location="..." {
    key_alias_enter "⏎"
    key_alias_space "␣"
    key_alias_esc   "⎋"
    key_alias_tab   "⇥"
}

Before: ENTER select After: ⏎ sel

Example 6: Custom hint template

Change how each hint is structured. The default is "{key} {action}" which renders as two styled blocks (key block + label block). A custom template renders as a single block instead:

zjstatus-hints location="..." {
    hint_format "{key}:{action}"
}

Before: n new x close (two-tone blocks) After: n:new x:close (single-color, ultra-compact)

Another option — action name first:

hint_format "{action}[{key}]"
// Result: new[n] close[x] full[f]

Example 7: Custom colors

Override the Zellij palette colors with your own hex values:

zjstatus-hints location="..." {
    // Global — applies to all hints
    key_fg   "#ffffff"
    key_bg   "#6e5fb7"
    label_fg "#cccccc"
    label_bg "#4c435c"

    // Per-label — override specific actions
    quit_key_bg   "#ff0000"
    quit_label_bg "#cc0000"

    // Per-mode + per-label — most specific
    pane.new_key_bg "#00ffcc"
}

Colors cascade: mode-specific → label-specific → global → Zellij palette. Each of the four color slots (key_fg, key_bg, label_fg, label_bg) resolves independently, so you can mix and match at different levels.

Example 8: Full compact setup (everything combined)

A real-world config combining all features for a tight statusbar:

plugins {
    zjstatus-hints location="file:~/.config/zellij/plugins/zjstatus-hints.wasm" {
        pipe_name "zjstatus_hints"
        hide_in_base_mode true
        max_length "0"
        overflow_str "…"

        // Compact keys
        modifier_style "symbol"
        separator " · "
        max_keys "4"

        // Short labels
        alias_fullscreen  "full"
        alias_split_right "S→"
        alias_split_down  "S↓"
        alias_rename      "ren"
        alias_half_page   "½pg"
        alias_increase    "inc"
        alias_decrease    "dec"
        alias_select      "sel"
        alias_break_pane  "break"
        alias_detach      "det"
        alias_manager     "mgr"

        // Symbolic keys
        key_alias_enter "⏎"
        key_alias_space "␣"

        // Colors matching a dark purple theme
        key_fg   "#ffffff"
        key_bg   "#6e5fb7"
        label_fg "#cccccc"
        label_bg "#4c435c"
    }
}

[neoighodaro]

bump

[neoighodaro]

Configuration examples

Every example below is independent — pick what you need, ignore the rest.

Example 1: Just make keys shorter

The simplest change. Turns Ctrl + n into ^n and Alt + h into M-h:

zjstatus-hints location="..." {
    modifier_style "symbol"
}

Before: Ctrl + p pane Ctrl + t tab Ctrl + n resize After: ^p pane ^t tab ^n resize

If you prefer C-n / A-h notation instead, use "short".

Example 2: Add separators between hints

By default hints are glued together. A separator makes them easier to read:

zjstatus-hints location="..." {
    separator " · "
}

Before: n new x close f fullscreen After: n new · x close · f fullscreen

Other ideas: " | ", " ⋅ ", " " (just a space for subtle spacing).

Example 3: Too many keys per action? Limit them

Zellij merges shared_except keybindings into every mode. This often means a single action shows 6–8 alternative keys. max_keys trims it:

zjstatus-hints location="..." {
    max_keys "4"
}

Before: Alt =|Alt +|=|+|Alt -|- resize ←|h|j|↓|↑|k|→|l increase After: Alt =|Alt +|=|+ resize ←|h|j|↓ increase

Set to "2" or even "1" for maximum compactness.

Example 4: Rename long action labels

Some labels like split right, fullscreen, half page eat up space. Rename them with alias_ options (use underscores for spaces):

zjstatus-hints location="..." {
    alias_fullscreen  "full"
    alias_split_right "S→"
    alias_split_down  "S↓"
    alias_rename      "ren"
    alias_half_page   "½pg"
    alias_select      "sel"
}

Before: r split right d split down f fullscreen ENTER select After: r S→ d S↓ f full ENTER sel

You can alias any label that appears in the bar. Common ones: new, close, fullscreen, float, embed, split right, split down, rename, move, select, resize, increase, decrease, scroll, page, half page, search, edit, detach, manager, config, plugins, about, break pane, sync.

Example 5: Replace special key names with symbols

ENTER, SPACE, ESC etc. can be replaced with Unicode symbols:

zjstatus-hints location="..." {
    key_alias_enter "⏎"
    key_alias_space "␣"
    key_alias_esc   "⎋"
    key_alias_tab   "⇥"
}

Before: ENTER select After: ⏎ sel

Example 6: Custom hint template

Change how each hint is structured. The default is "{key} {action}" which renders as two styled blocks (key block + label block). A custom template renders as a single block instead:

zjstatus-hints location="..." {
    hint_format "{key}:{action}"
}

Before: n new x close (two-tone blocks) After: n:new x:close (single-color, ultra-compact)

Another option — action name first:

hint_format "{action}[{key}]"
// Result: new[n] close[x] full[f]

Example 7: Custom colors

Override the Zellij palette colors with your own hex values:

zjstatus-hints location="..." {
    // Global — applies to all hints
    key_fg   "#ffffff"
    key_bg   "#6e5fb7"
    label_fg "#cccccc"
    label_bg "#4c435c"

    // Per-label — override specific actions
    quit_key_bg   "#ff0000"
    quit_label_bg "#cc0000"

    // Per-mode + per-label — most specific
    pane.new_key_bg "#00ffcc"
}

Colors cascade: mode-specific → label-specific → global → Zellij palette. Each of the four color slots (key_fg, key_bg, label_fg, label_bg) resolves independently, so you can mix and match at different levels.

Example 8: Full compact setup (everything combined)

A real-world config combining all features for a tight statusbar:

plugins {
    zjstatus-hints location="file:~/.config/zellij/plugins/zjstatus-hints.wasm" {
        pipe_name "zjstatus_hints"
        hide_in_base_mode true
        max_length "0"
        overflow_str "…"

        // Compact keys
        modifier_style "symbol"
        separator " · "
        max_keys "4"

        // Short labels
        alias_fullscreen  "full"
        alias_split_right "S→"
        alias_split_down  "S↓"
        alias_rename      "ren"
        alias_half_page   "½pg"
        alias_increase    "inc"
        alias_decrease    "dec"
        alias_select      "sel"
        alias_break_pane  "break"
        alias_detach      "det"
        alias_manager     "mgr"

        // Symbolic keys
        key_alias_enter "⏎"
        key_alias_space "␣"

        // Colors matching a dark purple theme
        key_fg   "#ffffff"
        key_bg   "#6e5fb7"
        label_fg "#cccccc"
        label_bg "#4c435c"
    }
}

Works great, I just forked the repo and applied your changes and made my own build. I added some additional options like italicize and make transparent bg (i like minimal). Thanks so much.

[y0usaf]

Split out the transparent-background follow-up from neoighodaro's fork into a focused PR on top of this branch:

• feat: add transparent_bg option for minimal hint styling AdamsGH/zjstatus-hints#1

It adds transparent_bg true to suppress key/label backgrounds for both the default renderer and custom hint_format, while keeping foreground colors + palette fallback behavior unchanged.

[dadigu]

Will this feature be merged any time soon? I would love be have this available :)