button

Clickable button widget. Emits a callback id (string) routed by the engine to component.onCallback, or wires up a closure when called inside a Z.app builder. Accepts top-level style shortcuts (bg, color, fontSize, bold, padding, border, borderWidth, minWidth, minHeight, tooltip, enabled).

Exports

• button(text: string?, callbackId: any?, opts: ButtonOpts?) -> WidgetNode — build a button widget node. The 2nd arg may be a string callback id, a closure (auto-wired in Z.app), or an options table when no 3rd argument is provided.

Types:

• ButtonOpts = { id?, classes?, class?, style?, onClick?, bg?, color?, fontSize?, bold?, padding?, border?, borderWidth?, minWidth?, minHeight?, tooltip?, enabled?, paint? }

Usage

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

btn("Save", "save:click")                              -- string callback id
btn("Save", function() print("clicked") end)            -- closure (inside Z.app)
btn("Save", { onClick = "save:click", bg = "#222" })  -- JS-style opts shape

Notes

• Passing a closure outside a Z.app builder errors at builder time — closures can't cross the Luau↔Rust FFI boundary, so they only auto-wire inside an app router.
• The 2-arg Z.btn(text, opts) shape is supported: if slot 2 is a table and slot 3 is missing, the callback is pulled from opts.onClick. Guards against the silent-dead-button bug tracked by #3059.
• See docs/guides/zui-cheatsheet.md for the three callback patterns.