Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sphere.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

Modals are small, focused UI flows. Use them for confirmations, forms, and multi-step flows. Simple to use, but capable of handling more complex interactions when needed.

​
Creating

local Dialog = require(UIComponents.Dialog)
local Modal = Dialog.New()

Output

FooterButtons Table
The footer button definitions. Modify before calling :Show(). See Footer Buttons.Results Table
The resolved values from all UI elements, keyed by their UniqueId.Events Table • Read-Only
Bindable events for the modal lifecycle.Stack Table • Read-Only
The current page stack. Shared with child modals pushed via :Push().Internal Read-Only
  • UniqueId String
    Auto-generated GUID used to identify this modal instance.
  • RuleSet Table
    All registered validation rules. Populated by :AddRule().
  • Layout Table
    The page and element definitions built by :Page(), :Add(), and :Grid().

​
Layout

​
Page

Pages are steps in the modal. Use multiple pages for wizards or multi-step flows. 
local Page = Modal:Page()

Modal:Page(Index: number?): PageBuilder

type PageBuilder = {
    Add: <T>(self: PageBuilder, Type: T | string, UniqueId: string?) -> ElementData<T>,
    Grid: (self: PageBuilder, Callback: GridBuilder) -> (),
}

type GridBuilder = (
    AddToGrid: <T>(Position: Vector2, Type: string | T, UniqueId: string?) -> ElementData<T>,
    CreateNestedGrid: (Callback: GridBuilder) -> {Type: "__grid", Children: {any}}
) -> ()

Input

Index Number?
The page to retrieve by index.

Output

Add Function
Adds a full-width block element to the page. See Add.Grid Function
Adds elements using an inline coordinate system. See Grid.

​
Add

Adds a full-width block element to the page. Pass a type string for preset components or a Roblox Instance to parent it directly into the modal. 
local Element = Page:Add("TextBox", "title")
Element.Config.PlaceholderText = "Input short summary"

--//Preset component
Page:Add(Type: string, UniqueId: string?): ElementData

--//Custom instance
Page:Add(Instance: GuiObject): ElementData

Input

Type String | Instance • Required
Any Instance parents directly into the modal and does not expose UIFlexMode, Config or Execute.Config Label
Type-specific configuration fields. Not available on raw Instance elements.UniqueId String
Key used to store this element’s value in Modal.Results. Omit for display-only elements.

Output

UIFlexMode Enum
Controls how the element stretches inside its container. See UIFlexMode.Config Table
Type-specific configuration fields. Not available on raw Instance elements.Execute Function
Called when the element’s value changes. Not available on raw Instance elements.

​
Grid

Adds elements using a coordinate system, enabling inline multi-column layouts. Grids can be nested. 
Page:Grid(function(Add, Grid)
    Add(Vector2.new(1, 1), "ToggleButton", "option_a")
    Grid(Vector2.new(2, 1), function(Add2)
        --//Nested grid
    end)
end)

Page:Grid(Callback: GridBuilder): ()

type GridBuilder = (
    AddToGrid: <T>(Position: Vector2, Type: string | T, UniqueId: string?) -> ElementData<T>,
    CreateNestedGrid: (Callback: GridBuilder) -> {Type: "__grid", Children: {any}}
) -> ()

Input

Position Vector2 • Required
The column/row coordinate for this element inside the grid.Callback Function • Required
add and recursive grid function.

​
Groups

Groups link multiple selection elements together. Works with ToggleButtons, CheckBoxes, RadioButtons, and PillButtons. 
local Group = {
    Exclusive = true,
    Required = 1,
    UniqueId = "Severity"
}
Assign the group table to Element.Config.Group on each element that should participate. 
type Group = {
    Exclusive: boolean?,
    Required: number?,
    Limit: number?,
    UniqueId: string,
}

Input

UniqueId String • Required
The key used to store the group’s result in Modal.Results.Exclusive Boolean
When true, only one option in the group can be selected at a time.Required Number
Minimum number of selections required before the modal can be submitted.Limit Number
Maximum number of selections allowed in the group.
The footer renders action buttons at the bottom of the modal. The defaults are Cancel and Submit, in that order. Modify Modal.FooterButtons before calling :Show(). 
Modal.FooterButtons.Submit = nil

Modal.FooterButtons.Confirm = {
    UniqueId = "submit",
    Title = "Confirm",
    Type = "Primary",
    Order = 2,
    Callback = function()
        print("Confirmed!")
    end,
}
Both Submit and Cancel can be modified or removed.
Modal.FooterButtons.Submit.Title = "Delete"
Modal.FooterButtons.Submit.Type = "Danger"
When a modal is displayed via :Push(), the Cancel button is automatically relabeled to Back. There is no need to define a separate Back button.
type FooterButton = {
    UniqueId: string,
    Title: string,
    Type: "Primary" | "Secondary" | "Danger" | "Ghost",
    Order: number,
    Callback: () -> (),
}

Input

UniqueId String • Required
Unique identifier for the button. Use "submit" to mark the button that triggers validation.Title String • Required
The label shown on the button.Type String • Required
Visual style. Accepted values: Primary, Secondary, Danger.Order Number • Required
The position of the button in the footer row. Lower numbers appear first.Callback Function • Required
Called when the button is pressed.
Validation only runs on buttons whose UniqueId is "submit".

​
Validation

​
AddRule

Registers a validation function that runs before the modal can be submitted. All rules must return true for submission to proceed. 
Modal:AddRule(function(Results)
    return Results.AgreedToTOS == true
end)

Modal:AddRule(Rule: (Results: {[string | number]: any}) -> boolean): ()

Input

Rule Function • Required
Receives the current Results table. Return true to allow submission, false to block it.

​
Resolve

Manually triggers all registered validation rules and fires the Validate event. 
Modal.Events.Validate:Fire()
Validation only works if a footer button with UniqueId = "submit" exists.

​
Displaying a modal

Results will be nil if the modal is cancelled.

​
Show

Displays the modal and returns a handle with an OnComplete signal. 
local Status = Modal:Show()
Status.OnComplete:Connect(function(Results)
    print(Results)
end)

Modal:Show(): {OnComplete: RBXScriptSignal}

Output

OnComplete RBXScriptSignal • Read-Only
Fires when the modal is resolved. Passes the Results table to connected callbacks.

​
Push

Pushes a child modal on top of the current one. The child shares the same stack. The cancel button becomes Back, and the parent resumes when the child resolves. 
Modal:Push("ConfirmDialog", {message = "Are you sure?"})

Modal:Push(
    Modal: string | Modal,
    ...: any
): {OnComplete: RBXScriptSignal}

Input

Modal String | Modal • Required
A template name string or an existing Modal instance to push onto the stack.… Any
Optional parameters forwarded to the template function.

Output

OnComplete RBXScriptSignal • Read-Only
Fires when the pushed modal resolves. The parent modal then resumes.

​
Templates

Templates let you define reusable modal layouts and register them by name.

​
Register

ModalController:Template("ConfirmDestructiveAction", function(Params)
    local Modal = ModalController.New()

    local Page = Modal:Page()
    Page:Add("Text", "warning").Config.Text = "This action cannot be undone."

    Modal.FooterButtons.Submit.Type = "Danger"
    Modal.FooterButtons.Submit.Title = "Delete"

    return Modal
end)

ModalController:Template(Name: string, Builder: (params: any?) -> Modal): ()

Input

Name String • Required
The key used to reference this template when importing or pushing.Builder Function • Required
A function that receives optional params and returns a fully configured Modal instance.

​
Import

Retrieves a registered template and returns a configured Modal instance. 
local Modal = ModalController.Import("ConfirmDestructiveAction", {foo = "bar"})
if Modal then
    Modal:Show()
end

ModalController.Import(Name: string, ...: any?): Modal?

Input

Name String • Required
The name of the registered template to import.… Any
Optional parameters forwarded to the template’s builder function.

Output

Modal Modal
The configured modal instance returned by the builder. Returns nil if the template name is not found.

​
Results

Results are populated when the modal resolves. You can access them two ways.

​
Event

Use this when you want to react immediately after the modal closes. 
local Handle = Modal:Show()
Handle.OnComplete:Connect(function(Results)
    print(Results)
end)

​
Property

Use this to read the results any time after the modal completes, as long as it hasn’t been destroyed. 
local Results = Modal.Results
You can also write to Modal.Results manually to pre-populate or override values.