Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Roblox/roact/llms.txt

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

Roact is a declarative UI library for Roblox Lua, closely modeled on Facebook’s React. Instead of manually creating, parenting, and mutating Roblox Instance objects, you describe what your UI should look like using lightweight element trees — and Roact takes care of creating, updating, and destroying the underlying Instances to match. This separation of description from implementation makes complex, dynamic interfaces far easier to reason about, test, and maintain.

​
How Roact works

In traditional Roblox UI code, you imperatively call Instance.new, set properties, set Parent, and track every change yourself. Roact flips this model: you write a function or component that returns an element tree, Roact reconciles that tree against the current state of the game, and only the parts that changed are touched. This is the same virtual-DOM approach React popularised for the web, adapted for Roblox’s Instance hierarchy. 
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Roact = require(ReplicatedStorage.Roact)

-- Describe the UI as a tree of elements (no Instances created yet)
local element = Roact.createElement("ScreenGui", {}, {
    Label = Roact.createElement("TextLabel", {
        Text = "Hello, world!",
        Size = UDim2.new(1, 0, 1, 0),
    }),
})

-- Roact creates the real Instances and keeps them in sync
local handle = Roact.mount(element, game:GetService("Players").LocalPlayer.PlayerGui, "HelloWorld")

​
Key concepts

Elements

An element is a plain Lua table that describes an Instance or component — its class, properties, and children. Elements are cheap to create and never touch the DOM directly.

Components

Components are reusable building blocks. Roact supports function components for simple, stateless UI and stateful components (extending Roact.Component) for UI that needs lifecycle methods and internal state.

State & Lifecycle

Stateful components can hold internal state and respond to lifecycle events such as didMount, didUpdate, and willUnmount, giving you full control over how your UI initialises and cleans up.

Events & Bindings

Roact provides Roact.Event and Roact.Change prop markers for connecting to Roblox Instance events and property-changed signals. Roact.createBinding gives you reactive values that update Instance properties without a full reconcile.

​
Full API surface

Roact exposes a focused, stable public API that maps closely to React’s:
APIPurpose
Roact.createElementCreate a virtual element describing a Roblox Instance or component
Roact.createFragmentGroup multiple elements without an extra parent Instance
Roact.ComponentBase class for stateful components
Roact.PureComponentStateful component with shallow-equality shouldUpdate
Roact.mount / unmount / updateMount, destroy, or update a virtual tree
Roact.createRef / Roact.RefObtain a direct reference to a rendered Instance
Roact.forwardRefCreate a component that forwards a ref to a child Instance
Roact.createBinding / joinBindingsReactive values for zero-overhead property updates
Roact.createContextShare data through the component tree without prop-drilling
Roact.PortalRender children into a different part of the Instance tree
Roact.oneChildUtility to safely unwrap a single child from a children table
Roact.NoneSentinel value to explicitly remove a property from an Instance
Roact.Event / Change / ChildrenProp markers for events, property-change handlers, and children

​
How Roact differs from direct Instance manipulation

Direct manipulation works fine for simple, static UI, but it scales poorly. When state changes you must remember which Instances to update and in what order. Roact eliminates this bookkeeping: re-render your component with new state and the reconciler figures out the minimum set of changes needed. Lifecycle hooks let you run setup and teardown logic at precisely the right moment, and context lets you share data across deep trees without threading props through every intermediate layer.
Roact’s API is intentionally very close to React’s. If you already know React, most concepts transfer directly. The main differences are Roblox-specific: class names like "TextLabel" instead of HTML tags, UDim2 and Color3 values instead of CSS strings, and Roact.Event/Roact.Change instead of onClick-style props.

​
Next step

Ready to add Roact to your project? Head to the Installation guide to get set up in minutes.

Build docs developers (and LLMs) love

Get started for freeTalk to us