UI

Schema-driven UI for Roblox, written in Luau. A page is a ModuleScript that returns a plain table describing it; the library builds it, shows and hides it, and cleans up everything it set up while shown. Client-only singleton.

It covers page lifecycle and layers (pages, overlays, modals), navigation hosts with back history, input on every platform (mouse, touch, gamepad selection, drag and drop, holds, keybinds), animation and transitions, stores and two-way binding, theming on native UI Styling, components (virtualized grids and lists, tabs, sliders, toggles, progress bars, text inputs, toasts, tooltips, confirm dialogs), UI sound, viewport previews, and 2D particles.

Install

[dependencies]
UI = "jadonbp/ui@1.0.0"

Use

-- Client loader
local UI = require(ReplicatedStorage.Packages.UI)

UI.Configure({ Pages = ReplicatedStorage.Client.UI.Pages })
UI.Initialize()

UI:Show("Inventory", { Tab = "Hats" })

-- ReplicatedStorage.Client.UI.Pages.Inventory (plain data: no require of UI, no setup at load)
return {
	Frame = function()
		return Players.LocalPlayer.PlayerGui:WaitForChild("Main").Inventory
	end,
	Layer = { Type = "Page" },
	Transition = "Slide",

	Behaviors = {
		Close = {
			OnActivated = function(page)
				page:Hide()
			end,
		},
	},
	Buttons = {
		Close = { Target = "Header.Close", Behavior = "Close" },
	},

	Bindings = {
		Count = { Target = "Header.Count", Property = "Text", Store = InventoryCount },
	},

	OnShow = function(page, data)
		-- Everything connected here is cleaned up when the page hides
		page:Observe(Coins, function(page, coins)
			page.Frame.Header.Coins.Text = tostring(coins)
		end)
	end,
}

Configure is called with a dot (UI.Configure, UI.Initialize); everything else uses a colon (UI:Show, UI:Hide, UI:Back, UI:Confirm, UI:Toast).

Global switches are stores: UI.Stores.ReducedMotion:Set(true) and UI.Stores.UISounds:Set(false).

Sound

A theme carries its sound set in Values.Sounds, referenced anywhere a sound is expected as "$Name". A sound is an asset id or a spec:

Sounds = {
	Click = { Id = "rbxassetid://1", Volume = 0.6 },
	-- Variants play in turn, one per play (round-robin)
	Hover = { Ids = { "rbxassetid://2", "rbxassetid://3", "rbxassetid://4" }, PitchVariance = 0.03 },
	Error = "", -- empty until the sound exists: plays nothing, reports nothing
},

Give either Id or Ids, not both. Volume, PlaybackSpeed, PitchVariance, MinInterval and Looped apply to whichever variant plays. The throttle (MinInterval, 0.05 s by default) is per sound, so a slot's variants share it.

License

MIT