Skip to content

Lua Widgets

EasyBar Lua widgets are node-based.

You create nodes, keep their handles, and update them with methods such as node:set(...) and node:subscribe(...). You do not return widget trees directly.

Lua widgets are the right tool when you want:

  • custom text, icons, or layout that built-ins do not provide
  • shell-command integration or lightweight local scripting
  • event-driven behavior tied to app changes, mouse input, timers, or helper-agent updates
  • small personal workflows without touching the native Swift codebase

If you have not decided whether Lua is the right tool yet, read Built-ins Vs Lua.

Lua widgets are trusted local scripts. EasyBar gives each widget file its own API scope, but it does not sandbox arbitrary widget code.

Minimal widget

local clock

clock = easybar.add(easybar.kind.item, "clock", {
    position = "right",
    order = 10,
    label = os.date("%H:%M"),
    interval = 60,
    on_interval = function()
        clock:set({
            label = os.date("%H:%M"),
        })
    end,
})

Mental model

Lua widgets follow this model:

  1. create nodes with easybar.add(...)
  2. store returned handles
  3. update nodes with node:set(...)
  4. subscribe to events with node:subscribe(...)
  5. let EasyBar render the current node state

The Lua runtime is for custom widgets and user-specific behavior. Built-in platform-integrated widgets should usually stay native when possible.

User-facing guides

Exact API reference

The generated API reference is useful when you need exact function names, event names, and property fields:

Use the guides for concepts and patterns. Use the reference pages for exact API details.

Contributor internals

Runtime architecture, process boundaries, socket transport, registry internals, rendering internals, and generated-artifact notes live under Lua Runtime Internals.