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.

With Roact installed, the best way to understand how it works is to render something on screen. This guide walks you through the classic “Hello, Roact!” example — a TextLabel mounted into PlayerGui — and explains exactly what each line does. By the end you’ll have a working UI element rendered entirely through Roact’s declarative API.
This guide assumes you have already installed Roact into ReplicatedStorage. If you haven’t done that yet, follow the installation guide first.

​
The complete script

Here is the full script you will write. Don’t worry if it’s unfamiliar — the steps below break it down line by line. 
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local Roact = require(ReplicatedStorage.Roact)

local app = Roact.createElement("ScreenGui", {}, {
    HelloWorld = Roact.createElement("TextLabel", {
        Size = UDim2.new(0, 400, 0, 300),
        Text = "Hello, Roact!"
    })
})

Roact.mount(app, Players.LocalPlayer.PlayerGui)

​
Walkthrough

1

Create a LocalScript in StarterPlayerScripts

In Roblox Studio, expand StarterPlayer in the Explorer panel, then right-click StarterPlayerScripts and choose Insert Object → LocalScript. This script will run on the client when a player joins, which is where UI code belongs.If you are using a Rojo filesystem workflow, create the file at:
src/StarterPlayer/StarterPlayerScripts/HelloRoact.client.lua
2

Require Roact and the Players service

At the top of the script, grab the services you need and load Roact:
local ReplicatedStorage = game:GetService("ReplicatedStorage")
local Players = game:GetService("Players")

local Roact = require(ReplicatedStorage.Roact)
require(ReplicatedStorage.Roact) returns the Roact API table, giving you access to createElement, mount, Component, and every other public function.
3

Describe the UI with createElement

Next, build a virtual element tree — a plain Lua table structure that describes what you want on screen. No Roblox Instances are created at this point.
local app = Roact.createElement("ScreenGui", {}, {
    HelloWorld = Roact.createElement("TextLabel", {
        Size = UDim2.new(0, 400, 0, 300),
        Text = "Hello, Roact!"
    })
})
Roact.createElement takes three arguments:
  • Type — a string matching a Roblox Instance class name (e.g. "ScreenGui", "TextLabel") or a component function/class.
  • Props — a table of Instance properties and event handlers. An empty table {} means “use defaults”.
  • Children — a table of named child elements. The key HelloWorld becomes the Name property of the resulting Instance.
Here the tree has a root ScreenGui containing one child TextLabel that is 400×300 pixels and displays the text "Hello, Roact!".
4

Mount the tree into PlayerGui

Finally, hand the element tree to Roact and tell it where to put the real Instances:
Roact.mount(app, Players.LocalPlayer.PlayerGui)
Roact.mount walks the virtual tree, creates the corresponding Roblox Instances, sets their properties, and parents them under PlayerGui. The UI is now live.
5

Run the game and verify

Press Play in Studio (or publish and join). You should see a large gray label with the text “Hello, Roact!” appear in the top-left area of the screen.If nothing appears, check the Output window for errors and confirm that Roact exists in ReplicatedStorage and that the LocalScript is inside StarterPlayerScripts.

​
What you should see

When the game runs, a 400×300 pixel TextLabel will appear on screen displaying Hello, Roact!. It will use all default Roblox styling — white background, black text — because no additional properties were set. That’s intentional: the goal here is to prove the rendering pipeline works before adding complexity.
Roact.mount returns a tree handle. You can pass that handle to Roact.update to swap in a new element tree (for example when your app state changes), or to Roact.unmount to cleanly destroy all the Instances Roact created and run any component teardown logic. Hold on to the handle if you need to control the tree’s lifetime.
local handle = Roact.mount(app, Players.LocalPlayer.PlayerGui)

-- Later, update with new props:
-- handle = Roact.update(handle, newApp)

-- Or tear everything down:
-- Roact.unmount(handle)

​
Next steps

You’ve rendered your first Roact element. From here you can explore:
  • Elements and components — learn how createElement works in depth and how to build reusable function and stateful components.
  • State and lifecycle — use Roact.Component to build UI that reacts to changing data.
  • Events — wire up Roact.Event and Roact.Change to respond to user input.
  • Bindings — use Roact.createBinding for efficient, fine-grained property updates without full reconciliation.

Build docs developers (and LLMs) love

Get started for freeTalk to us