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 in the right-side ordering region (or the corresponding Native status-item order)
  • 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 in EasyBar's right region and acts as a relative ordering hint in EasyBar Native
  • order = 10 controls render ordering among other root nodes
  • label = ... sets the displayed text
  • interval = 60 asks EasyBarKit to call on_interval 60 seconds after the widget registers, then every 60 seconds after that
  • on_interval = function() ... end updates the node in place

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

Where this widget goes

The selected frontend recursively loads every .lua file below its configured widgets directory. EasyBarKit keeps its single-file examples flat below examples/; only the multi-file inbox demo uses a subdirectory. No category or filename is required by the loader. Put reusable helpers below shared/ so they load only through require(...) instead of being discovered as widgets.

That directory is configured with [app].widgets_dir in the selected frontend config. See EasyBar App Settings or EasyBar Native Configuration.

Expanding the widget

Once the basic widget works, you can add:

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

Next steps