Status bars

Most plugin surfaces are click-driven menus and buttons. Status bars are different: they show compact, continuously visible information that updates on a timer and as the file manager context changes.

Register one with waydir.register_bar. The update(ctx) function is called on load, every interval seconds, and (unless refresh_on_change = false) whenever its context changes. Return visible = false to hide the bar for the current context.

waydir.register_bar({
  id = "project_status",
  scope = "pane",
  title = "Project",
  icon = "code",
  interval = 10,
  refresh_on_change = true,
  update = function(ctx)
    if not ctx.dir:match("/src") then
      return { visible = false }
    end
    return {
      visible = true,
      items = {
        { type = "badge", text = "src", level = "info" },
        { type = "text", text = ctx.dir },
        { type = "button", id = "refresh", action = "refresh", icon = "refresh", tooltip = "Refresh" },
      },
    }
  end,
})

Scope

Scope	Where it renders
"global"	Above Waydir's bottom status bar. One instance for the window.
"pane"	Per pane, above pane status strips such as Git. Receives pane-local context.

Definition

Field	Meaning
id	Bar id inside this plugin.
scope	"global" or "pane".
title	Label shown at the start of the bar.
icon	Named builtin glyph or bundled image path. See Icons.
interval	Refresh cadence in seconds, clamped between 2 and 3600; 0 disables periodic refresh.
refresh_on_change	Refresh when the context changes (folder, selection, active pane). Defaults to true.
settings	Optional schema merged with the plugin's normal settings.
update(ctx)	Returns the current visible state.
click(ctx)	Optional handler for button clicks; receives ctx.item_id.

Bar context

Bar ctx includes the usual ctx.dir, ctx.paths, ctx.count, ctx.plugin_dir, and ctx.settings. It also adds:

Field	Meaning
ctx.scope	"global" or "pane".
ctx.pane	The pane the bar renders in (pane scope).
ctx.is_active	Whether this pane is the active one.
ctx.item_id	In click(ctx), the id of the clicked button.

Items

update returns items, a list of compact UI elements:

Item type	Fields
text	text, optional level
badge	text, optional level
icon	icon, optional level
button	id, optional text, icon, tooltip, action
separator	no fields

level can be info, success, warn, or error.

Buttons

A button emits a click(ctx) call with ctx.item_id set to the button id. A button with action = "refresh" refreshes the bar without calling click - use it for a manual refresh control.

waydir.register_bar({
  id = "counter",
  scope = "global",
  title = "Items",
  update = function(ctx)
    return {
      visible = true,
      items = {
        { type = "text", text = ctx.count .. " selected" },
        { type = "separator" },
        { type = "button", id = "show", text = "Show", icon = "eye" },
      },
    }
  end,
  click = function(ctx)
    if ctx.item_id == "show" then
      waydir.toast(ctx.count .. " items selected")
    end
  end,
})