PurchaseLoadingOverlay — Animated purchase loading UI for Roblox

PurchaseLoadingOverlay is a lightweight client-side Luau module that shows a full-screen loading presentation while a purchase or other asynchronous operation is in progress.

The module creates its UI at runtime, dims the screen, and animates a rotating loading image. It only handles presentation; your game remains responsible for starting and resolving purchases.

Quick example

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local PurchaseLoadingOverlay = require(
	ReplicatedStorage.Packages.PurchaseLoadingOverlay
)

local overlay = PurchaseLoadingOverlay.new()

overlay:Show()

-- Start or await your purchase flow here.
task.wait(2) -- Replace with your awaited purchase operation.

overlay:Hide()
overlay:Destroy()

When no Parent is supplied, the generated ScreenGui is placed in the local player's PlayerGui.

🚀 Features

• Fade in a full-screen background while a loading image expands into view
• Rotate the loading image continuously while the overlay is shown
• Customize the background, image, layout, display order, and animation timing
• Respect Roblox reduced-motion settings
• Observe shown, hidden, and open-state changes
• Reuse the generated UI across multiple show/hide cycles
• No external runtime dependencies

🛠️ Installation

ModuleScript

Place init.luau in a client-accessible ModuleScript, for example:

ReplicatedStorage
└── Packages
    └── PurchaseLoadingOverlay
        └── init.luau

Require and construct it from a LocalScript:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local PurchaseLoadingOverlay = require(
	ReplicatedStorage:WaitForChild("Packages"):WaitForChild("PurchaseLoadingOverlay")
)

local overlay = PurchaseLoadingOverlay.new()

Wally

Add the package to your project's wally.toml:

[dependencies]
PurchaseLoadingOverlay = "biotoxin495/purchase-loading-overlay@1.0.0"

Construct the controller on the client.

Basic usage

Show() opens the overlay and starts the spinner. Call Hide() after the operation finishes:

overlay:Show()

local success, result = pcall(function()
	return performPurchase()
end)

overlay:Hide()

if success then
	print("Purchase flow finished", result)
end

The package does not call MarketplaceService or decide whether a transaction succeeded. Connect it to whichever purchase or asynchronous flow your game uses.

To skip the closing animation, call overlay:Hide(true). Call overlay:Destroy() when the controller is no longer needed.

---

API reference

PurchaseLoadingOverlay.new(config?) -> PurchaseLoadingOverlay

Creates the controller and its generated ScreenGui. The UI is parented to config.Parent when provided, or to the local player's PlayerGui by default. Create the controller on the client.

Configuration

All fields are optional.

Example configuration:

local overlay = PurchaseLoadingOverlay.new({
	Parent = game.Players.LocalPlayer.PlayerGui,
	DisplayOrder = 100,
	LoadingImage = "rbxassetid://15734250582",
	TransitionDuration = 0.25,
	RespectReducedMotion = true,
})

overlay:Show()

Shows the background, opens the loading image, and starts its rotation. Repeated calls while already shown are ignored.

overlay:Hide(immediate?)

Stops the rotation and animates the overlay closed. Pass true to skip the closing tween:

overlay:Hide(true)

overlay:IsShown() -> boolean

Returns whether the overlay is currently shown.

overlay:CheckIfOpen() -> boolean

Compatibility alias for IsShown().

overlay:GetOpenChangedSignal() -> RBXScriptSignal

Returns the same signal exposed as overlay.OpenChanged.

overlay:Destroy()

Cancels active tweens and tasks, destroys internal events, and removes the generated ScreenGui. A destroyed controller cannot be reused.

Signals

overlay.Shown:Connect(function()
	print("Purchase loading started")
end)

overlay.Hidden:Connect(function()
	print("Purchase loading finished")
end)

overlay.OpenChanged:Connect(function(isOpen)
	print("Open state:", isOpen)
end)

OpenChanged fires when a show or hide transition starts. Hidden fires after the closing transition finishes.

Notes

• The default UI is a black full-screen background with transparency 0.5 while shown.
• The loading image defaults to rbxassetid://15734250582 and rotates once every 1.5 seconds.
• The image expands from zero size at the top-center to UDim2.new(0.6, 0, 0.2, 0) at the center of the screen.
• Every generated Instance belongs to the controller. Show() and Hide() reuse the UI; Destroy() removes it.
• The package does not start purchase prompts, listen to remotes, or make transaction decisions.

Project structure

PurchaseLoadingOverlay/
├── init.luau
├── README.md
├── wally.toml
├── sourcemap.json
└── LICENSE

License

MIT — see LICENSE.

---

made with ❤️ by biotoxin495