Notifications

It sucks, will be remade later

Notifications are small, dismissible UI messages sent to players. Use them for alerts, confirmations, and interactive prompts. Simple to send, but capable of embedding buttons and inputs for richer interactions.

local Sphere = script:FindFirstAncestor("Sphere")
local NotificationController = require(Sphere.Core.API.Notifications)

Creating

local Notification = NotificationController.New()

Properties

Title String • Required
The heading shown on the notification. Must be set before calling :Send().

Description String
Secondary body text displayed below the title.

Icon String
Asset ID for a small icon shown on the notification.

Thumbnail String
Asset ID for a larger thumbnail image.

Duration Number
How long in seconds the notification stays visible. Defaults to 5. Set to math.huge to keep it open indefinitely.

BackgroundColor3 Color3
Background fill color. Defaults to Color3.fromRGB(0, 0, 0).

BackgroundTransparency Number
Background transparency from 0 to 1. Defaults to 0.1.

---

Items

Items are interactive elements embedded inside a notification. Add them with :Add() before calling :Send().

Add

Appends an interactive item to the notification. Supported types are "Button" and "Input".

Annotation

Notification:Add(Type: "Button" | "Input"): Button | Input

Example

Adds a button to the notification, sets its label, and connects a callback that fires when the player presses it.

local Button = Notification:Add("Button")
Button.Title = "Confirm"
Button:Connect(function(player, response)
    print(player.Name, "clicked", response)
end)

Input

Type String • Required
The item type to create. Must be "Button" or "Input".

Output

Returns a Button or Input object depending on the type passed. See Button and Input for available fields and methods.

---

Button

A clickable action embedded in the notification. Fires connected callbacks when the player interacts with it.

Annotation

type Button = {
    Title: string?,
    Variant: string?,
    LeadingIcon: string?,
    TrailingIcon: string?,

    Connect: (self: Button, func: (...any) -> any, disconnectAfterRemoval: boolean?) -> number?,
    Disconnect: (self: Button, funcId: (number | "disconnectAfterRemoval")?) -> (),
    Destroy: (self: Button) -> (),
}

Example

Creates a primary button with a leading icon. The callback fires when the player presses it and auto-disconnects once the notification is closed.

local Button = Notification:Add("Button")
Button.Title = "Accept"
Button.Variant = "Primary"
Button.LeadingIcon = "rbxassetid://1"

Button:Connect(function(player, response)
    print(player.Name, "responded:", response)
end, true)

Fields

Title String
The label shown on the button.

Variant String
Visual style variant for the button.

LeadingIcon String
Asset ID for an icon shown to the left of the title.

TrailingIcon String
Asset ID for an icon shown to the right of the title.

Methods

Connect Function
Registers a callback fired when the button is pressed. The callback receives (player: Player, response: string). Pass disconnectAfterRemoval = true to auto-disconnect when the notification is closed. Returns the function index.

Disconnect Function
Removes a registered callback. Pass a numeric index to remove one, "disconnectAfterRemoval" to remove all auto-disconnect callbacks, or omit to clear all.

Destroy Function
Removes this button from the notification.

---

Input

A text field embedded in the notification. Connected callbacks fire when the player submits the input.

Annotation

type Input = {
    Title: string?,
    PlaceholderText: string,
    DefaultValue: string,
    MaxLength: number,
    AutoSubmit: boolean,
    ClearTextOnFocus: boolean,
    ClearTextOnSubmit: boolean,
    MultiLine: boolean,

    Connect: (self: Input, func: (...any) -> any, disconnectAfterRemoval: boolean?) -> number?,
    Disconnect: (self: Input, funcId: (number | "disconnectAfterRemoval")?) -> (),
    Destroy: (self: Input) -> (),
}

Example

Collects a short text response from the player. The field clears after submission and caps input at 200 characters.

local Input = Notification:Add("Input")
Input.Title = "Reason"
Input.PlaceholderText = "Enter a reason..."
Input.ClearTextOnSubmit = true
Input.MaxLength = 200

Input:Connect(function(player, value)
    print(player.Name, "submitted:", value)
end)

Fields

Title String
Label shown above the input field.

PlaceholderText String
Ghost text shown when the field is empty. Defaults to "Type here...".

DefaultValue String
Pre-filled value when the notification appears. Defaults to "".

MaxLength Number
Maximum number of characters allowed. Defaults to math.huge.

AutoSubmit Boolean
When true, submits automatically as the player types. Defaults to false.

ClearTextOnFocus Boolean
When true, clears the field when the player focuses it. Defaults to false.

ClearTextOnSubmit Boolean
When true, clears the field after the player submits. Defaults to true.

MultiLine Boolean
When true, allows line breaks in the input. Defaults to false.

Methods

Connect Function
Registers a callback fired when the input is submitted. The callback receives (player: Player, value: string). disconnectAfterRemoval defaults to true for inputs. Returns the function index.

Disconnect Function
Removes a registered callback. Pass a numeric index to remove one, "disconnectAfterRemoval" to remove all auto-disconnect callbacks, or omit to clear all.

Destroy Function
Removes this input from the notification.

---

Sending

Send

Sends the notification to one player, a list of players, or all players. Returns a handle containing the active send’s UUID.

Annotation

Notification:Send(Target: Player | {Player} | "all"): {UUID: string}

Examples

Single player
Sends to one player and stores the UUID for later use with :Close().

local Notification = NotificationController.New()
Notification.Title = "Welcome!"
Notification.Description = "Thanks for joining."
local Handle = Notification:Send(player)
print(Handle.UUID)

All players
Broadcasts to every connected player. The notification auto-dismisses after 10 seconds.

local Notification = NotificationController.New()
Notification.Title = "Server restarting"
Notification.Description = "The server will restart in 60 seconds."
Notification.Duration = 10
Notification:Send("all")

With buttons
Sends a persistent invite with Accept and Decline buttons. Each button closes the notification for that player on press. disconnectAfterRemoval is set so callbacks clean up automatically when the notification is dismissed.

local Notification = NotificationController.New()
Notification.Title = "Team invite"
Notification.Description = `{player} wants you to join their team.`
Notification.Duration = 60

local Accept = Notification:Add("Button")
Accept.Title = "Accept"
Accept:Connect(function(player)
    print("The player had accepted!")
    Notification:Close(Handle.UUID, player)
end, true)

local Decline = Notification:Add("Button")
Decline.Title = "Decline"
Decline:Connect(function(player)
    print("The player had declined...")
    Notification:Close(Handle.UUID, player)
end, true)

local Handle = Notification:Send(player)

Input

Target Player | Table | String • Required
Who to send the notification to. Pass a Player instance, a table of Player instances, or "all" to broadcast to every connected player.

Output

UUID String • Read-Only
The GUID identifying this active send. Use it with :Close() to dismiss the notification early.

Title must be set before calling :Send() or an error will be thrown.

---

Close

Dismisses a specific active send by UUID. Optionally targets a single player; omit to remove the notification for everyone.

Annotation

Notification:Close(UUID: string, Player: Player?): ()

Examples

Close for everyone
Dismisses the notification for all players who received it. Useful for timed or event-driven cleanup.

local Handle = Notification:Send("all")

task.delay(30, function()
    Notification:Close(Handle.UUID)
end)

Close for one player
Dismisses the notification only for a specific player, leaving it visible for everyone else.

local Handle = Notification:Send("all")
Notification:Close(Handle.UUID, player)

Input

UUID String • Required
The UUID returned by :Send() identifying the active send to dismiss.

Player Player
If provided, only dismisses the notification for this player. Omit to dismiss it for all players.

Closing a send also disconnects all callbacks whose disconnectAfterRemoval is true.

---

Destroy

Removes all active sends of this notification across all players and clears all its items.

Annotation

Notification:Destroy(): ()

After calling :Destroy(), the notification object should not be reused. All items are cleared and all sends are closed.

---

Duration

By default, notifications auto-dismiss after 5 seconds. Set Duration before calling :Send() to change this.

--// Dismiss after 10 seconds
Notification.Duration = 10

--// Never auto-dismiss
Notification.Duration = math.huge

When Duration is math.huge, the notification stays visible until :Close() or :Destroy() is called manually.