Start typing to search packages!
roblox-ui-kit
By @hurreman
Roblox
Mirrored from Wallyroblox-ui-kit
hurreman/roblox-ui-kit is the shared React UI kit for hurreman's Roblox games (Magical Neighborhood, Slime Nebula, Steal an Egg). It's built on jsdotlua React 17.2.1.
It gives you:
- Themeable components. Each game keeps its own look, and a surface can be a flat colour or 9-slice image art.
- Motion: UIAnimator, staggers and the panel pop.
- A panel host with focus mode and gamepad selection.
- Toasts, driven by a push API.
- Store hooks that work with any change-signalling client store.
- A loading screen shell that runs from ReplicatedFirst, and topbar icons (TopbarPlus).
Most of it comes from Magical Neighborhood's src/client/UI. The rest is new: Tabs, ProgressBar, virtualised List/Grid, Tooltip, selection groups, Viewport, PanelHost and the state helpers.
Install
wally.toml:
[place]
shared-packages = "game.ReplicatedStorage.Packages"
[dependencies]
UIKit = "hurreman/roblox-ui-kit@0.4.0"
React = "jsdotlua/react@17.2.1"
ReactRoblox = "jsdotlua/react-roblox@17.2.1"
Run wally install, then map Packages into ReplicatedStorage in the Rojo project. The kit finds React next to itself (Wally links it), or else in ReplicatedStorage.Packages.
Quick start
local Kit = require(ReplicatedStorage.Packages.UIKit)
local React, ReactRoblox = Kit.React, Kit.ReactRoblox
local e = React.createElement
Kit.configure({ extends = Kit.Presets.Base, colors = { accent = Color3.fromRGB(80, 220, 200) } })
local panels = Kit.PanelRegistry.new()
panels:register("Rewards", { component = RewardsPanel, animatesClose = true })
local function App()
local scale = Kit.useViewportScale()
return e("Frame", { Size = UDim2.fromScale(1, 1), BackgroundTransparency = 1 }, {
Scale = e("UIScale", { Scale = scale }),
Tips = e(Kit.Tooltip.Provider, {}, {
Panels = e(Kit.PanelHost.Host, { registry = panels }),
Toasts = e(Kit.Toasts.View, { feed = toasts }),
}),
})
end
Use one root: a single ReactRoblox.createRoot in a ScreenGui with ResetOnSpawn = false and ZIndexBehavior = Sibling.
Everything on Kit loads the first time you touch it. So require is cheap, and a game only pays for the parts it uses.
Theming
There's one current theme per client. Kit.configure(theme) merges a partial theme over the theme it extends. When extends is left out, that's Kit.Presets.Base.
configure checks the result straight away. A missing required token, an unknown colour key, or a surface or text role that doesn't resolve raises an error then, not halfway through a render.
Kit.configure({ extends = Kit.Presets.MagicalNeighborhood, rarity = HouseTiers.RarityColors }) -- Magical Neighborhood
Kit.configure(SlimeNebulaTheme) -- a game's own table
Merge rules:
- Sections merge key by key.
- A surface token replaces the token of the same name. A 9-slice panel doesn't inherit the flat panel's stroke and corner.
falsecounts as a value, sostroke = falsemeans no outline.
Components that call Kit.useTheme() re-render when configure runs again. Plain-function primitives (Kit.Text, Kit.Panel, Block.Surface) pick up the new theme on their parent's next render.
To follow a runtime theme, as Slime Nebula's Theme.lua does with its Theme.Changed signal, call configure from that signal:
local function apply() Kit.configure(SlimeNebulaTheme.toKit()) end
apply()
SlimeNebulaTheme.Changed:Connect(apply)
Sections
| Section | What it drives |
|---|---|
colors | Named colours. The kit reads these semantic keys: text, textDim, stroke, panel, panelLight, accent, positive, negative, plus warning, close and disabled from Base. Any other keys are the game's own palette. A string value is an alias: accent = "gold". |
fonts | Font values by key. display and body are required. |
text | Text roles for Kit.Text { role = ... }. Each role is { font = key, color? = key, strokeColor?, strokeSize?, maxSize? }. Base has display, title, body, stat, label and dim. An unknown role falls back to display. |
space, radius | Scales: xs to xxl, sm to pill. Wherever a theme or a component takes a size, it takes a number or one of these keys. |
surfaces | Surface tokens (below). Required: panel, button, tab, tabActive, tooltip, track, fill, toast. |
block | variant ("flat", "studded" or "image"), studTile, face (the image variant's surface), lip, disabledStyle ("muted", the default: a disabled button keeps its hue, desaturated and darker; "color": it turns disabledColor), disabledColor ("disabled" by default; false keeps the block's own colour, as MagicalNeighborhood does) and style (the Block.Style numbers, including the depth knobs shadow, gloss, rim, hoverBrighten, pressScale, attentionScale, attentionEvery). |
window | Window's layout constants: ribbon height, title icon, close button, padding, fit margins, dim, panelColor. panelSurface draws the panel from a surface, such as a 9-slice frame, instead of a block. closeImage draws the close button as one image (hover grows it, a press dips it) instead of a block in closeColor. Depth: shadow (under the panel, "drop"), shadowCorner (match the panel art), ribbonSurface (ribbon art), body = "inset" (content in a panelInset well, bodyPadding). phone holds the phone layout's own tokens (below, inset, barHeight, barGap, padding, closeSize, closeInset, titleIcon, titleIconX, titleSize, body, bodyPadding); set it to nil for no phone layout. See "The phone layout". |
depth | The depth layers (see "Materials" below): shadows presets (drop, contact, glow), shadowInk, gloss, rim, inset, and beta (off: the Studio beta's inner shadows). |
progress | ProgressBar: inset, gloss, shimmer = { every, duration } (or false), flash (s), ghost, badgeSize, fillGradient. |
dialogue | DialogueBox and GuideBubble colours: panel, nameplate, choice, highlight, disabled, close, portrait. Also charsPerSecond. |
toast | kindColors (kind → colour), defaultColor, band, top, maxWidth. |
rarity | Rarity name → colour, used by ToastItem. Games pass their own ladder. |
Kit.Theme also exposes:
color(ref),space(v),radius(v),surface(ref, over?),role(name?),current(),onChanged(fn).ColorsandFonts: live mirrors with every colour resolved.Resolve: the pure resolver.
Surfaces
A surface token is either flat or image (9-slice). Every surface name and every surface prop takes either kind.
Flat:
panel = {
color = "panel", -- a colour key or a Color3
transparency = 0,
corner = "md", -- px or a radius key
stroke = { color = "stroke", thickness = 2, transparency = 0 },
gradient = { rotation = 90, top = 0.12, bottom = 0.12 }, -- the fill lightened/darkened (or colors = { a, b })
padding = "sm", -- adds a UIPadding
}
Image (9-slice). Setting image makes a token an image surface:
Kit.configure({
surfaces = {
panel = {
image = "rbxassetid://1234567890", -- the frame art
sliceCenter = Rect.new(48, 48, 208, 208),
sliceScale = 0.5, -- shrink the corners for a 2x texture
imageRectOffset = Vector2.new(0, 0), -- optional: one cell of a sprite sheet
imageRectSize = Vector2.new(256, 256),
tint = "panel", -- ImageColor3 (colour key or Color3)
padding = 14, -- keep content off the art's border
},
window = { extends = "panel", sliceScale = 0.75 }, -- inherit, then tweak
buttonPrimary = { extends = "panel", tint = "accent" },
},
block = { variant = "image", face = { image = "rbxassetid://...", sliceCenter = Rect.new(20, 20, 44, 44), sliceScale = 1 } },
window = { panelSurface = "window" },
})
How image surfaces behave:
scaleTypeis"Slice"whensliceCenteris set, and"Stretch"otherwise.- An image surface has no fill behind the art unless you give it a
color. - When a component passes a
color, it tints an image surface and fills a flat one. SoBlock { color = ... }works with both kinds. - A token can inherit from another with
extends = "<surface name>". A flat child of an image parent drops the image.
To draw a surface yourself: Kit.Surface.render { surface, over?, color?, tint?, size, onClick?, sink?, native?, children }, or e(Kit.Surface.Surface, ...), which forwards ref.
Materials
Flat colour plus a rounded corner reads as plastic. The kit adds the layers that make a surface look lit from above and resting on something. Any surface token can ask for them, and Block, ProgressBar, Window and Card use them by default:
| Layer | Token key | What it is |
|---|---|---|
| Shadow | shadow = "drop" | "contact" | "glow" | { blur, offset = { x, y }, spread, transparency, tint } | A UIShadow (released API). Its colour leans toward depth.shadowInk, never pure black; "glow" takes the surface's own colour. It follows the object's UICorner, so an image token needs a corner that matches its art. |
| Gloss | gloss = true | { share, strength, inset } | A top-only highlight band (per-corner radii on the top corners only). One per element. |
| Rim | rim = true | { strength } | Light along the top edge, fading down the sides. |
| Inset | inset = true | { share, strength } | A well's inner shadow from the top edge. With depth.beta it's the Studio beta's real UIShadow { Inset = true }. A published experience can't use that until Roblox ships it, so beta defaults to false. |
Kit.Depth.Shadow(ref, color?), Kit.Depth.Gloss { corner, ... }, Kit.Depth.Rim { corner } and Kit.Depth.Inset { corner } draw them by hand.
Budget: Roblox advises at most about 100 UIShadows on screen. Every Block, Card and Window adds one.
Art that the kit tints (Block faces, panels) should be flat and greyscale. The kit draws the gloss, so a face that bakes in its own shine doubles it.
Presets
| Preset | Look |
|---|---|
Base | Neutral dark: BuilderSans, flat surfaces, flat blocks (no studs). It's the default. |
MagicalNeighborhood | Magical Neighborhood's current look: LuckiestGuy + Nunito, the purple panels, the studded blocks, and its Window and dialogue colours. Its old palette keys (gold, orange, green, red, purple, white, dim) are kept as aliases of the semantic ones. |
The stories add a third, story-only theme, NineSlice, with every surface made of 9-slice art. Paste your own art into its SliceImage control.
Components
All views are pure: no remotes, no game modules. Data and callbacks come in as props.
Kit.Text { text, role?, size?, color?, strokeSize?, maxSize?, rich?, textSize?, autoHeight?, alignY?, ... } | Outlined text in a text role. By default it is scaled to fit its box (titles, stats, labels). For multi-line body copy give textSize: a fixed size that wraps; add autoHeight (with a height-0 size) to grow the box with the text. Kit.Theme.stat("+30%", "money") makes rich text with the figure in a heavier weight. |
Kit.Panel { surface? = "panel", color?, radius?, strokeSize?, onClick?, sink?, ... } | A themed panel. sink = true swallows clicks. |
Kit.Block.Surface / Kit.Block.Button { color, icon?, label?, layout?, variant?, onClick?, disabled?, disabledColor?, attention?, ... } | The chunky block: a lip with a contact shadow, a top gloss band and a rim. Hover brightens the face and grows the icon; a press sinks and squashes the face. A disabled button ignores hover, press and clicks and is muted: same hue, desaturated (block.disabledStyle). disabledColor picks a colour; false keeps the normal one. attention = true sweeps a shine across it and pulses it gently (a ready reward). Kit.Block.Style holds the live theme.block.style. |
e(Kit.Card, { selected?, color?, size?, onClick?, ... }, children) | A list row or tile resting on its panel: the card surface, or cardSelected (accent outline and glow). |
e(Kit.Window, { title, icon?, color?, size: Vector2, onClose, subtitle?, header?, dim?, closeOnBackdrop?, closing?, closeTo?, scroll? }, children) | The modal shell. It pops in, and closing plays a wind-up and shrink before onClose runs. On a desktop or tablet it shrinks itself to fit the screen; on a phone it takes the screen instead (The phone layout). subtitle adds a dim caption line at the top of the body (children go below it). scroll puts the body's children in a scrolling frame that grows with them — pass it wherever the content can be taller than the body, which on a phone is most panels. |
Kit.Backdrop.element { dim?, onActivated?, ref?, zIndex? } | The modal dim. It overshoots the safe area. |
Kit.IconLabel { image, text, size, ... } | An icon and text laid out as one group. |
e(Kit.PointArrow, { position, label?, rightEdge?, bob? }), e(Kit.Spotlight, { hole, label?, bob? }) | Onboarding pointers. |
Kit.Burst.emit(parent, origin, { glyphs, colors?, count?, distance?, gravity? }) | Fire-and-forget particle bursts. |
e(Kit.GuideBubble, { lineId, speaker, text, portrait?, fallbackIcon?, bottom?, dismissOnTapOutside?, onDismiss }) | The tutorial guide's speech bubble. bottom lifts it (px above the screen's bottom edge). dismissOnTapOutside lets a tap anywhere else put it away; the tap still reaches the world. |
e(Kit.DialogueBox, { speaker, text, nodeId, choices: { ChoiceView }, onChoose, onClose }) | NPC dialogue. Each ChoiceView is { Index, Text, Disabled?, DisabledReason?, Highlighted? }. |
e(Kit.Tabs, { tabs = { { id, label, icon?, badge? } }, selected, onSelect, vertical?, ... }) | A tab strip. L1 and R1 cycle the tabs on a controller. |
e(Kit.ProgressBar, { value, tween?, label?, labels? = { left, center, right }, badge? = { text | icon, color }, ticks?, vertical?, track?, fill?, fillColor?, shimmer?, flash?, ghost? }) | value is a number or a binding. A binding moves the fill every frame with no re-render. The track is an inset well. The fill grows from a round cap, so a small value is a short pill and never a square chip. It has a gloss band, a shimmer and a flash when it gains. Labels size themselves to the bar, and the badge is a round chip over the left end ("Lv 3"). Bars under about 18 px drop the gloss and shimmer; under about 14 px they drop the labels. A fill surface with an image draws that art instead. |
e(Kit.List, { items, itemHeight, renderItem, keyOf?, overscan? }), e(Kit.Grid, { items, cellSize, renderItem, columns?, stretch?, gap? }) | Virtualised scrolling: only the rows in view are mounted. |
e(Kit.Tooltip.Provider, ...), Kit.Tooltip.use(content), Kit.Tooltip.merge(handlers, props), Kit.Tooltip.Bubble | Tooltips. They follow the mouse, or sit above the selected element on a gamepad. |
e(Kit.ErrorBoundary, { name, onError?, fallback? }, children) | Catches a render error in its subtree: warns, calls onError once (deferred), and shows fallback (default nothing). A remount starts fresh. PanelHost wraps every panel in one. |
e(Kit.Viewport.View, { model, yaw?, pitch?, zoom?, fov?, spin?, surface? }), Kit.Viewport.pool, Kit.Viewport.Pool.new | Model previews framed to fit. Clones are pooled per template, and spin runs through a ref. |
Kit.Toasts.new(config?), toasts:push / notify, e(Kit.Toasts.View, { feed, paused?, focus?, top?, rarityColors?, renderAnnouncement? }), e(Kit.ToastItem, ...), Kit.ToastSubjects.new({ state }) | Notifications (below). |
Kit.LoadingScreen.run(config), Kit.LoadingScreen.new(config) | The loading screen shell (below). Plain instances, no React. |
The phone layout
A panel designed for a desktop cannot be scaled onto a phone. The Window used to shrink anything that didn't fit, which keeps the whole panel on screen — and takes the text and the tap targets down with it. Measured in Studio's device emulator on a 667 × 375 phone, a 520 × 410 panel came out at a Fit scale of 0.609: its 15 px body copy rendered 9 px and its 52 px close button rendered 32 px, under the 44 px a thumb needs. Every panel in the game was in that state; none of them was usable.
So a phone gets a different layout, not a smaller one. When the screen's short side is at most
theme.window.phone.below (520 real px), the Window:
- ignores
sizeand becomes the screen, inset byphone.inset, at scale 1 — so a design px is a real px and nothing shrinks; - moves the ribbon and the close button inside, into a full-width title bar
phone.barHeighttall (nothing overhangs a panel that is already the screen), withphone.closeSize≥ 44; - drops the body well, which costs 20 px of a body that is now about 250 px tall;
- hands the content a box that is wider and much shorter than the designed one.
That last point is the part a game has to answer. The panel's own content has to give instead of
scaling: pass scroll so the rows scroll, drop a grid to fewer columns, or lay the panel out again.
local L = Kit.useLayout() -- { phone, viewport, area }; re-renders when the viewport changes
return e(Kit.Window, {
title = "Upgrades",
size = PanelSize.of("Upgrades"), -- ignored on a phone
scroll = L.phone,
onClose = close,
}, { Rows = e(Rows, { columns = if L.phone then 1 else 2 }) })
Kit.Fit is the model on its own, as pure arithmetic: Fit.isPhone(viewport, window) and
Fit.solve { viewport, area, design, window } → { phone, size, fit, cut, body }. A game's specs can
require it and assert against their own panel sizes without a DataModel — which is the point, because
a panel that quietly grows past what a phone can show shrinks its own buttons.
phone = nil in a theme's window turns the whole thing off and panels shrink everywhere, as before
0.5.0.
Toasts
The queue (Kit.Toasts.Queue) has no store wiring. The game pushes into it:
local toasts = Kit.Toasts.new({
kindTimes = { hatch = 4.2 }, -- fixed durations per kind
focusKinds = { tutorial = true }, -- what may interrupt focus mode
uncollapsedKinds = { hatch = true }, -- every one gets its own turn
still = subjects:checker(), -- reminders that go stale (below)
})
Net.event("Notify").OnClientEvent:Connect(function(kind, text, rarity, about)
toasts:notify(kind, text, { rarity = rarity, about = about })
end)
These are Magical Neighborhood's rules:
- Announcements show one at a time, sized to how long the text takes to read. A repeat collapses into the one before it as ×N.
- Feedback kinds (
error,collect) show immediately, beside any announcement. pausedholds announcements back.focuslets onlyfocusKindsthrough, and when focus ends, only the fresh ones are played.- A reminder (a toast with
about) is dropped, or leaves early, oncestill(about)returns false.
renderAnnouncement(item, leaving) draws special kinds yourself, such as Magical Neighborhood's hatch card.
Reminder subjects. A reminder's about is a subject string, "<head>:<rest>". Kit.ToastSubjects keeps the game's check for each head and answers still:
local subjects = Kit.ToastSubjects.new({ state = function() return Store.state end })
subjects:register("crop", function(tile, state) return state.farm.plots[tile].phase == "grown" end)
local toasts = Kit.Toasts.new({ still = subjects:checker() })
toasts:notify("info", "Your Pumpkin is ready!", { about = "crop:" .. tile })
The toast still shows when it has no about, when no check is registered for its head, when the check errors, or when there's no state yet.
Loading screen
Kit.LoadingScreen is Magical Neighborhood's loading screen, turned into a shell. It has:
- a gradient with painted parallax layers. Each layer fades in once it and everything behind it has downloaded.
- a logo image, with a text fallback.
- a progress bar with a status line, and rotating tips.
- an exit: the corner pieces part, the scene pushes in, and everything fades.
It preloads what the game hands it and waits on the game's own gates:
LoadingScreen.run({
title = "MY GAME", subtitle = "Loading the fun", tips = { "Tip: ..." },
layers = { { name = "Sky", id = "rbxassetid://...", kind = "wide", depth = 0.1 } },
preload = function() return { images = require(Shared.UiAssets), later = { sounds = Music } } end,
steps = {
{ label = "Building your plot...", progress = 0.5, wait = function() return player:GetAttribute("PlotReady") == true end },
{ label = "Almost there...", progress = 0.85, wait = function() return player.Character ~= nil end },
},
minShowTime = 3,
})
- A gate is a function (polled), a signal (it waits for the next fire) or nil.
maxWait(45 s) caps the whole screen.- In Studio, the Workspace attribute
HoldLoading = truekeeps the screen up. - A game that drives the steps itself uses
LoadingScreen.new(config), thenscreen:waitFor,setProgress,preload,waitPreloadandfinish. screen:setLayersswaps the art (say, when the season arrives late).screen.root,screen:layerZ(name)andonFramelet a game add flourishes between the layers.
It needs no other kit module, so it can run from ReplicatedFirst. But ReplicatedFirst starts before ReplicatedStorage has replicated, so wait for the module itself instead of requiring the Wally link. The header of src/LoadingScreen.luau has the snippet. Roblox's default loading screen covers that wait. A screen that must be up on the very first frame has to live in ReplicatedFirst itself.
Topbar icons
Kit.useTopbar(icons, { hidden? }) keeps a list of TopbarPlus icons in step with React state:
- Each icon is created once per
name, and restyled when its label, caption, side, order orenabledchanges. - The latest
onClickis always the one called. hidden = true(a full-screen panel is open) steps every icon aside, exceptkeepWhenHiddenones.
TopbarPlus is optional. The kit finds TopbarPlus in ReplicatedStorage.Packages, or you pass it as options.Icon. Without it, the hook warns once and does nothing. Kit.useTopbar.Preview draws the same list as pills, for stories.
Kit.useTopbar({
{ name = "Settings", label = "⚙️", caption = "Settings", order = 1, onClick = toggleSettings },
{ name = "Favorite", label = "⭐", align = "Right", order = 1, enabled = not favorited, onClick = promptFavorite },
}, { hidden = panelOpen })
Panels, focus and gamepad
local panels = Kit.PanelRegistry.new()
panels:register("Shop", { component = ShopPanel, animatesClose = true }) -- focus = true by default
panels:register("Map", { component = MapPanel, focus = false, selection = false })
panels:open("Shop", { tab = "gems" }, "dock") -- args, source
e(Kit.PanelHost.Host, { registry = panels, focusMode? = true, blur? = true, panelProps? }) renders the one open panel. Each panel gets { name, args, closing, onClose, close, requestClose }. Pass closing and onClose through to Kit.Window. To close from inside the panel (e.g. after a successful action), call requestClose(): it plays the close animation. close() skips it.
When a panel with animatesClose = true is replaced or closed, it stays mounted with closing = true until its close animation calls onClose.
Errors stay contained. Each panel renders inside a Kit.ErrorBoundary. A panel that throws while rendering is warned about ([roblox-ui-kit] panel <name> crashed while rendering), closed in the registry with source "error" and unmounted. Other panels and the root keep running. Wrap other independent regions (HUD widgets, world boards) yourself: e(Kit.ErrorBoundary, { name, onError?, fallback? }, children).
While a panel with focus is open, Kit.FocusMode blurs the world and hides the touch controls. Each panel sits in a Kit.SelectionGroup.
Hooks: Kit.PanelHost.usePanel(registry) -> name, args and Kit.PanelHost.useIsOpen(registry, name).
Bridging to a game's modal bus. Every change carries a source, so a bridge can ignore the changes it made itself. Slime Nebula's UnifiedModal / ActionEvents would bridge like this:
panels:onPanelChanged(function(name, previous, change)
if change.source == "bus" then return end -- we did that: don't echo it back
if previous then ActionEvents.ModalClosed:Fire(previous) end
if name then ActionEvents.ModalOpened:Fire(name) end
end)
ActionEvents.ModalOpened.Event:Connect(function(legacyName)
if not panels:get(legacyName) then panels:close(nil, "bus") end -- a legacy panel opened: close ours
end)
e(Kit.SelectionGroup, { active?, default?, restore?, gamepadOnly?, confine? }, children):
- Confines D-pad navigation to the group, using
SelectionGroupandSelectionBehavior = Stop. - Selects a default when the group opens: a ref, a descendant's name, or the top-left selectable.
- Restores the earlier selection when it closes. Nested groups restore in order (
Kit.Selection.Stack).
By default it only takes the selection when the player is on a controller. In Studio, set the workspace attribute ForceGamepad = true to test without a pad.
Kit.Input has:
prefersGamepad(),prefersKeyboard(),touchControlsShown(),mode()padGlyph(keyCode?)onModeChanged(fn),useInputMode()useViewportScale({ design?, min?, max? })
Kit.TouchButtons.place(action, "left" | "above") puts ContextActionService buttons next to the jump button.
State hooks
Kit.useSignal(store, read?, equal?) | Re-renders when the store fires. It understands OnChanged(fn) -> disconnect (Slime Nebula's clients), an OnChanged or Changed signal (RBXScriptSignal, BindableEvent, any :Connect), subscribe(fn) (Magical Neighborhood's Store), or a signal on its own, including a bare RBXScriptSignal such as bindable.Event (fields are probed safely, so a strict signal never throws). read defaults to store.state, then store:get(), else nil. |
Kit.useSlice(state, keys) | A table of just keys, rebuilt only when one of them changes by reference. Give it to React.memo children. |
Kit.useClock({ now?, step? }) -> binding, Kit.useClock.at(deadline?, { now?, slack? }) | Countdowns without per-frame re-renders. useClock is a binding of now() written once per whole step (map labels from it). useClock.at re-renders once just after deadline, for state that flips when a countdown ends. Server timers: now = function() return workspace:GetServerTimeNow() end. Pure maths: Kit.Clock. |
Kit.useSlice.fromStore(store, keys) | The same, subscribed straight to a store. The component re-renders only when one of its own keys changes. |
Kit.DeltaStore.new() | A snapshot mirror that applies a full state or a delta: :apply(changes, full?, removed?), :set, :reset, .Changed. Plus DeltaStore.diff(prev, next) for the server side, and DeltaStore.connect(store, syncRemote, helloRemote?). |
Kit.useArrowTarget(id, ownRef?), Kit.useArrowTarget.instance(id), Kit.ArrowTargets.get / observe | Onboarding arrows find UI by id, not by instance name: ref = Kit.useArrowTarget("shop"). |
Kit.Signal, Kit.Slice, Kit.Subscribe | The pure helpers underneath. |
Motion: Kit.UIAnimator, Kit.useStagger(trigger, collect, preset?, options?) and Kit.usePanelPop. Inside React, pass wrap = false (useStagger already does). For values that change every frame, use bindings or refs, never setState.
Other hooks: Kit.useAttrs, Kit.useScreenArea, Kit.useLayout ("The phone layout"), Kit.useTopBarPlacement, and Kit.useTopbar (above).
Tools
Kit.SyncThemeTokens comes from Slime Nebula. It's for a theme whose tokens Studio can override through a Configuration's attributes. The trap there: an attribute seeded earlier silently shadows a later edit to the code's DEFAULTS. The tool reports where the two disagree and reconciles them in either direction. Run it from the Studio command bar, in Edit mode:
local sync = require(game.ReplicatedStorage.Packages.UIKit).SyncThemeTokens.new({
module = game.ReplicatedStorage.ClientModules.UI.Theme, -- its DEFAULTS table, re-required fresh on each call
config = game.ReplicatedStorage.UI.Theme, -- the Configuration
})
print(sync.Report()) -- also Push(...keys), Clear(...keys), Seed()
Conventions
- Views are pure. No remotes, no game modules: data comes in as props.
tests/specs/Static.specchecks thatsrc/never requires game code. - Every component has a UI Labs story in
stories/, with mock props and style controls. Each story also gets theme controls: Preset, Accent, and the 9-slice art. - Motion uses UIAnimator (
wrap = false) or TweenService on refs. - Per-frame values use bindings or refs, never
setStateevery frame.
Development
aftman install
wally install
lune run tests/run
rojo build dev.project.json -o build/dev.rbxl
rojo serve dev.project.json
lune run tests/runruns the unit specs: theme resolution, the toast queue, DeltaStore, Slice and Subscribe, the panel registry, the selection stack, arrow targets, the virtual range maths, the viewport pool, toast subjects, the loading screen's helpers and SyncThemeTokens' comparison. It also runs static checks: every file compiles, everyrequire(script...)path resolves, every export loads, and every component has a story.lune run tests/run Toastfilters by spec name.rojo serve dev.project.jsonmaps the kit toReplicatedStorage.RobloxUIKitwith the stories beside it, for UI Labs.
Publishing
Published on the public Wally index as hurreman/roblox-ui-kit (0.1.0 on 2026-10-23, then 0.2.0, then 0.3.0 on 2026-10-26, 0.4.0 on 2026-10-30, 0.5.0 on 2026-11-14). 0.3.0 adds LoadingScreen, useTopbar, ToastSubjects, SyncThemeTokens, GuideBubble's bottom and dismissOnTapOutside, and block.disabledColor. 0.4.0 adds the depth layers (depth theme section, surface shadow / gloss / rim / inset, Kit.Depth), Kit.Card, a rebuilt ProgressBar (drawn well and fill growing from a round cap, labels, badge, exact, shimmer, flash; theme section progress), Block's hover / squash / attention and muted disabled style (block.disabledStyle), and Window's drop shadow, body = "inset" well and ribbonSurface. 0.5.0 adds the phone layout: Kit.Fit (the Window's geometry as pure arithmetic), Kit.useLayout, the window.phone theme tokens and Window's scroll. It also fixes a Viewport bug worth knowing about: React destroys a host instance before running the effect cleanup that hands its clone back to the pool, so a parked clone could come back destroyed, and parenting a destroyed instance throws — a grid of previews took its whole panel down with it. The pool now has an alive option and a discard, and Viewport.View treats parenting the clone as the liveness test and takes another on failure. Changed in 0.5.0: on a screen whose short side is at most 520 real px, a Window no longer shrinks to fit — it becomes the screen at scale 1, with its ribbon and close button inside a title bar, and size is ignored there (see "The phone layout"). A panel whose content was drawn for a desktop body will overflow a phone one, so pass scroll or give it a phone layout; window.phone = nil restores 0.4.0's behaviour. Changed in 0.4.0: a disabled Block.Button is muted in its own hue by default (disabledStyle = "color" for the old grey); an image surface token no longer gets a UICorner (it notched 9-slice corners), its corner now only shapes its depth layers and its shadow caster. For a new release, bump version in wally.toml (and Kit.VERSION in src/init.luau), run lune run tests/run, check wally package --list shows only src, the project, LICENSE, README.md and wally.toml (Wally 0.3.2 ignores include and .gitignore, so dev files are kept out through exclude), then:
wally login
wally publish
Consumers then add UIKit = "hurreman/roblox-ui-kit@<version>".
Package Details
Install command (Click to copy)
Version
0.5.0
License
MIT
Safe for commercial use
Automated license review — not legal advice.
