Skip to content

First Widget

This guide walks through the smallest useful Lua widget and explains each piece.

What we are building

We will create one clock widget that:

  • appears on the right side of the bar
  • shows the current time
  • refreshes once per minute

Minimal example

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,
})

How it works

easybar.add(...) creates one node and returns its handle.

The arguments are:

  1. the node kind, here easybar.kind.item
  2. a stable node id, here "clock"
  3. a property table describing placement, content, and behavior

Important fields

  • position = "right" places the node on the right side of the bar
  • order = 10 controls render ordering among other root nodes
  • label = ... sets the displayed text
  • interval = 60 asks EasyBar to call on_interval every 60 seconds
  • on_interval = function() ... end updates the node in place

The clock variable stores the handle returned by EasyBar, which lets the callback call clock:set(...) later.

Where this widget goes

EasyBar loads every *.lua file in your widgets directory.

That directory is configured with [app].widgets_dir in config.toml.

See App Settings.

Expanding the widget

Once the basic widget works, you can add:

  • an icon through icon = { string = "..." }
  • colors through label.color or color
  • click behavior through node:subscribe(...)
  • a popup through the popup property

Next steps