Controls overview

Every control is a method on a section. It takes one options table and returns a handle.

local handle = section:Toggle({ Text = "Enabled", Callback = print })

The fourteen#

Options every control shares#

Anything a control adds on top is documented on its own page.

These build the row itself:

These are read after the control is built, so they work the same on a control you registered yourself:

Save, Reapply and RevertOnClose are covered in Saving settings and Lifecycle.

Title, Description and Separator return a Roblox instance instead of a handle, so nothing in the second table reaches them. Their options are on Title, Description & Separator.

Handles#

Stateful controls return a handle with Get and Set:

local speed = main:Slider({ Text = "Speed", Min = 0, Max = 100, Default = 50 })
 
speed:Get()      --> 50
speed:Set(80)    --> updates the UI and fires Callback

Set returns true, or false and a reason when the value is refused:

local ok, why = dropdown:Set("Nowhere")   --> false, "value is not present in Options"

Pass true as a second argument to set the value without firing anything. A panic button can put every control back that way without re-running the work.

Every handle carries these:

handle.Instance is the card frame, for when you need the Roblox instance.

A handle also knows what it is, so you do not have to keep a parallel list of labels beside your config code:

local speed = main:Slider({ Text = "Walk speed", Save = true })
 
speed.Text      --> "Walk speed"
speed.Kind      --> "Slider"
speed.SaveKey   --> "My Script/Main/Slider/Walk speed"
speed.Section   --> the section it was built on

Name() and Key() are the same two values as methods. To walk every control in a window rather than one you already hold, see win:Controls().

Some controls add more. A dropdown, for example:

Callbacks#

Callback fires whenever the value changes, with the new value as its first argument:

main:Toggle({
    Text = "Godmode",
    Callback = function(enabled)   -- boolean
        print("godmode:", enabled)
    end,
})
 
main:Slider({
    Text = "FOV", Min = 70, Max = 120,
    Callback = function(value)     -- number
        workspace.CurrentCamera.FieldOfView = value
    end,
})
 
main:Dropdown({
    Text = "Target", Options = { "Nearest", "Lowest HP" },
    Callback = function(choice)    -- string
        targetMode = choice
    end,
})

A callback does not fire when a control is created. One exception: a Saved control that restored a value calls it once with that value. See Saving settings.

Where the call came from#

Ember calls your callback for reasons other than the user touching the control: a restored value at startup, FireOnStart, a re-apply after a respawn, a revert on close. A third argument says which, so you do not have to guess from timing:

main:Toggle({
    Text = "Announce",
    Save = true,
    Callback = function(on, _, origin)
        if origin and origin.initial then return end   -- came off disk, stay quiet
        win:Notify({ Title = on and "On" or "Off" })
    end,
})

origin is nil for an ordinary user-driven change, so if origin and origin.initial is the whole test. The startup-suppression timer this replaces also swallowed real errors for as long as it was open.

FireOnStart covers the other case: fire once at creation even when nothing was saved, so a control that starts non-default applies itself.

A toggle can name the two halves separately with OnEnabled and OnDisabled. See Toggle.

Turning a control off#

Every control takes Disabled, and every handle has the methods to change it later. A disabled control refuses input and looks like it is refusing.

local start = main:Button({
    Text = "Start the farm",
    ButtonText = "Go",
    Disabled = true,
    DisabledReason = "Pick a target first",
    Callback = beginFarm,
})
 
targetPicker:Set("Nearest")
start:Enable()

DisabledReason is shown as a tooltip while the control is disabled, so a dead button can say what would bring it back.

Explaining a control#

Any control takes Tooltip, shown while the pointer is over it.

main:Slider({
    Text = "Tick rate",
    Min = 1, Max = 60, Default = 30,
    Tooltip = "How often the farm re-scans. Lower is cheaper.",
})

SetTooltip(text) changes it later, and SetTooltip(nil) removes it. DisabledReason takes priority while the control is disabled.

Organising a long section#

Title, Description and Separator break a section into runs. See Title, Description & Separator.

Group puts rows in a container that collapses. See Groups and search.

Adding your own#

RegisterControl installs a builder as a section method, so your control is called like any built-in one and gets the same card, search indexing, Reapply and handle methods:

Ember.RegisterControl("Badge", function(section, opts)
    local card, slot = Ember.Controls.mount(section, opts)
 
    local value = Ember.Util.label(opts.Value or "", 13, Ember.Theme.accent)
    value.Size = UDim2.new(0, 0, 0, 22)
    value.AutomaticSize = Enum.AutomaticSize.XY
    value.Parent = slot
 
    return {
        Instance = card,
        Set = function(_, text) value.Text = tostring(text) end,
    }
end)
 
main:Badge({ Text = "Build", Value = Ember.Version })

Return a table with an Instance and Ember adds Show, Hide, SetVisible, Destroy, SetTooltip, SetDisabled, Disable, Enable, IsDisabled, Name and Key to it, along with the Text, Kind, SaveKey and Section fields — so a control you wrote appears in win:Controls() beside the built-in ones.

The pieces that example is built from — Util.label, Controls.mount, the Metrics sizes and the rest — are in Utilities and internals.

See them running#

Every control page carries a live preview of the real control, and the swatches above each one repaint it into any of the nine built-in themes. For all of them working together in one window, see the docs landing page or the full showcase.