tabs

Tab strip — a horizontal row of buttons with one highlighted as active. Each tab emits the callback id <onChange>-<key> so a single pattern handler can capture every click and update the active tab in state. Under a Z.app context the strip also intercepts arrow-key navigation (with wrap-around, skipping disabled tabs) and dispatches the same event a click would.

Exports

• tabs(items, activeKey, onChange, opts?) -> Node — returns the tab-strip widget node. Module returns the builder function directly.

Types:

• TabItem = { key: string, label?: string, icon?: string, enabled?: boolean }
• TabsOpts = { id?, app?, padding?, gap?, minTabWidth?, containerPadding?, style? }

Usage

local tabs = require("@builtin::modules.zui.widget.tabs")

local items = {
    { key = "entities", label = "Entities" },
    { key = "logs",     label = "Logs" },
}

tabs(items, state.activeTab, "main-tabs")

app:on("^main%-tabs%-(.+)$", function(_v, _id, key)
    state.activeTab = key
end)

Notes

• The wrapper emits { type = "tabs", ... }; the Z.defineWidget("tabs", ...) registration in zui.module/init.luau decodes that into the primitive hbox + btn tree the Rust renderer sees.
• activeKey and items are mirrored into widgetState so the per-strip key handler reads the live values at event time — closures never go stale across re-renders.
• Tab itself stays the focus-traversal key (egui's built-in cycle); only arrow keys are intercepted by the strip.