healthBar

Game-HUD horizontal health bar. Luau builder over canvas — emits a background rect plus a foreground fill rect scaled by current / max, with an optional centered numeric label. The wrapping canvas exposes ARIA progressbar semantics for the DOM mirror so screen readers report the current value.

Exports

• healthBar(current: number, max: number, opts: HealthBarOpts?) -> WidgetNode — module returns the builder function directly. Call Z.healthBar(...) via the zui re-export.

Options:

• showText: boolean? — overlay "current/max" centered. Default true.
• background: string? — empty-bar tint. Default "#3c1e1e".
• color: string? — fill color when gradient is not set. Default "#c83c3c".
• width: number?, height: number? — bar size. Defaults 200 x 24.
• label: string? — aria-label override. Default "Health".
• gradient: boolean | {{number, string}}? — true for the default 3-stop red→yellow→green, or a sorted {{ratio, "#rrggbb"}} list.
• id, classes, style — standard widget plumbing.

Usage

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

Z.healthBar(state.hp, state.hp_max, {
    showText = true,
    gradient = true,
    label    = "Player health",
})

-- Custom gradient stops:
Z.healthBar(hp, max, {
    gradient = {
        { 0,   "#000000" },
        { 0.5, "#777777" },
        { 1,   "#ffffff" },
    },
})

Notes

• Stops must be sorted ascending by ratio. Ratios outside [0, 1] are clamped. Fewer than 2 stops falls back to the default 3-stop palette.
• The fill rect is omitted when ratio == 0 so an empty bar's edge doesn't render a 0-width sliver.
• gradient (when truthy) overrides color.
• Stateless — no module state, safe to call every frame.