Dropdown
Choose one optional string from an ordered, scrollable list.
Create Dropdown#
Choose one optional string from an ordered, scrollable list.
The constructor returns a Dropdown handle. The snippet assumes section exists, as created in Quick start.
local dropdown = section:CreateDropdown({
Name = "Output mode", Flag = "output", Options = {"Quiet", "Detailed"},
Default = "Quiet", MaxVisibleOptions = 6,
Callback = function(value) print("Mode:", value or "No selection") end,
})
Open full size ↗
Open full size ↗Arguments#
| Option | Type | Default | Meaning |
|---|---|---|---|
| Options | {string} | {} | Ordered option list; copied. |
| Multi | boolean | false | Use an array selection when true. |
| Default | string? | nil | Initial single choice; unknown choice normalizes to nil. |
| Placeholder | string | "Select an option" | Empty-selection caption. |
| MaxVisibleOptions | integer | 6 | Between 1 and 20; long lists scroll. |
| Callback | function(string?) | nil | Receives the selection or nil. |
Also accepts common options: Name, Description, Disabled and Callback; stateful controls additionally support Flag, Persist and Sensitive.
Manage state#
dropdown:SetValue("Detailed", true)
dropdown:SetOptions({"Quiet", "Detailed", "Compact"})
dropdown:Clear()
dropdown:Open()
dropdown:Close()Returned methods#
| Method | Returns | Behavior |
|---|---|---|
| GetValue() | string? | Current string? value. |
| SetValue(value, notify?) | self | Silent by default; true calls Callback only after a changed normalized value. |
| SetDisabled(boolean) | self | Changes user availability without discarding the value. |
| IsDisabled() | boolean | Reads the requested disabled state. |
| Destroy() | nil | Removes this control and its subscriptions; safe to repeat. |
| GetOptions() | {string} | Independent ordered copy. |
| SetOptions(options, notify?) | self | Replaces options and normalizes selection. |
| Clear(notify?) | self | Clears to nil or {} for multi. |
| Open() | self | Requests opening if input is available. |
| Close(instant?) | self | Closes; instant defaults false. |
| IsOpen() | boolean | Reads the logical popup state. |
Behavior and limitations#
Options must be a dense array of nonempty strings. Duplicates are removed while preserving first occurrence order. Selection values are matched exactly, including case.
Only one Dropdown/ColorPicker popup can be open in a Window. Opening another closes the previous popup. Clicking the same trigger toggles genuinely closed/open; the outside handler excludes its trigger.
Placement uses available space. A popup below expands downward with its top anchored; above expands upward with its bottom anchored. Closing reverses toward the trigger, including interrupted tweens.
Outside mouse/touch, Escape, page switch, hide, minimize, disable and Destroy close the popup. Open() returning self does not guarantee that a blocked popup opened.
Single selection closes the popup. SetValue of an unknown option becomes nil. Configuration loading of a removed option can fall back to the available construction default; inspect warnings.
Default and SetValue accept a string or nil; other types assert. SetOptions validates a dense string array before replacement. It retains still-valid choices and reopens an already-open popup when available; notify=true calls Callback only if normalization changed the selection.