toggle

iOS-style on/off switch — a Luau builder over canvas. Draws a rounded pill background, a white circle knob sliding along its axis, and an optional text label next to it. Operable by mouse (click) and keyboard (Tab to focus, Enter/Space to flip).

Exports

• toggle(label, id, checked, opts?) -> Node — returns the toggle widget node. Module returns the builder function directly.

Types:

• ToggleOpts = { style?, width?, height?, onColor?, offColor?, knobColor?, onChange?, classes?, ariaLabel?, app? }

Usage

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

toggle("Lights on", "lights", state.lights, { onChange = "lights:toggle" })

-- Without onChange, the callback id defaults to the widget id:
toggle("Bypass", "fx:bypass", state.bypass)

Notes

• Under Z.app the internal <id>:click handler reads widgetState(id, "checked"), flips it, and dispatches onChange (or the widget id) with { value = newBool }. The Router unpacks data.value so function(v) end receives the new bool.
• Without Z.app the canvas's onClick routes directly to the caller's callback id and the legacy onCallback(id, _) pattern (caller flips its own local state) keeps working.
• DOM mirror surfaces as <canvas role="switch" aria-checked="…"> for screen-reader support.