dropdown

Combobox-style dropdown — Luau builder over Z.btn + Z.popup + Z.selectableList. Click-to-open, click-to-select, click-outside / Escape closes. Full keyboard navigation: the inner SelectableList handles ArrowUp/Down/Home/End + Enter/Esc, and the trigger button accepts ArrowDown / Enter / Space to open via generalised onKey.

Exports

• dropdown(id: string, options: { string }?, selected: number?, opts: DropdownOpts?) -> WidgetNode — build the trigger + popup. selected is the 1-based index of the active option; first call seeds ui.widgetState(id, "selected").

Types:

• DropdownOpts = { style: { [string]: any }?, classes: (string | { string })?, onChange: string?, pivot: string?, rowWidth: number?, rowHeight: number?, ariaLabel: string?, app: any? }
• WidgetNode = { [string]: any }

Usage

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

Z.dropdown("env", { "Dev", "Stage", "Prod" }, state.env, {
    onChange = "env:change",
})

app:on("env:change", function(v)
    state.env = v   -- v is the new 1-based index
end)

Notes

• ARIA roles: trigger is role="combobox" / aria-expanded; popup hosts a listbox. Focus moves to the row matching the current selection on open, and returns to the trigger on close.
• Per-id handlers (<id>-trigger, <id>:triggerKey, <id>:commit, <id>:dismiss) are registered once and deduped — re-renders don't accumulate handlers.
• selected is clamped to [1, #options] so out-of-range inputs don't crash the popup.