Style Guidelines¶

These guidelines keep Lua widgets predictable and easy to debug.

Use stable IDs¶

Node IDs should be stable across reloads:

easybar.add(easybar.kind.item, "brew_outdated", {
    position = "right",
})

Avoid dynamic IDs unless you are intentionally creating a dynamic list.

Always keep the handle returned by easybar.add(...) when the node needs updates or subscriptions.

local clock = easybar.add(easybar.kind.item, "clock", {
    label = os.date("%H:%M"),
})

Keep state in Lua variables and render from that state.

local count = 0
local widget

local function render()
    widget:set({
        label = tostring(count),
    })
end

Use group when multiple child nodes belong together visually.

Use child subscriptions when only specific parts should be clickable.

Prefer event subscriptions for real runtime events.

Use intervals only for polling external state.

Prefer easybar.exec_async(...) for slow commands.

Avoid expensive synchronous work in mouse handlers, interval callbacks, and frequent events.

Avoid doing too much work at file load time.

Good places for side effects: