Roact Documentation

Portals are a special type of component that allow you to render Roact-managed objects into a separate, non-Roact Instance (a target).

This is useful for rendering UI elements that need to exist outside of the current Roact tree hierarchy, such as full-screen modal dialogs that should reside in PlayerGui even if the component triggering them is deep within a different UI hierarchy.

Warning: Portals should only be used to target objects that are not already managed by Roact. Targeting a Roact-managed Instance with a Portal can lead to unexpected behavior or conflicts in instance management.

-- Example of a Portal targeting Workspace
local function PartInWorkspace(props)
	return Roact.createElement(Roact.Portal, {
		target = Workspace
	}, {
		SomePart = Roact.createElement("Part", {
			Anchored = true
		})
	})
end

Use Bindings when you need to manage specific, high-frequency, or external property values (like a number or string) without triggering a full component reconciliation.

Use Refs when you need to access the actual Roblox Instance object itself to call its methods (like :CaptureFocus()) or to pass the Instance as a property to another object (like NextSelectionLeft).

When rendering lists of elements, avoid using array indexes as keys. If an item is inserted at the beginning of a list, using indexes causes Roact to re-render every subsequent item because their index (and thus their key) has changed.

Instead, use stable, unique keys (such as an ID from your data) for each element in the list. This allows Roact to recognize that existing elements have simply moved rather than changed, significantly reducing the work required to update the Roblox UI.

for i, item in ipairs(items) do
	-- Use the item's unique ID as the key instead of the index 'i'
	itemList[item.id] = Roact.createElement(Item, {
		layoutOrder = i,
		icon = item.icon,
	})
end

A host component is a string representing a Roblox class name (e.g., "Frame", "ImageButton"). When used with Roact.createElement, the props passed to the component are applied directly as properties to the resulting Roblox Instance.

-- Example of a host component
local element = Roact.createElement("TextLabel", {
    Text = "Hello World"
})

To create a stateful component, extend Roact.Component using Roact.Component:extend("ComponentName").

Lifecycle Methods

• init(initialProps): Called once when the component is created. Use it to set up initial state via self:setState() or by assigning directly to self.state.
• render(): A pure function that returns an Element or nil. It must depend only on props and state. If a component renders nothing, it should explicitly return nil.
• shouldUpdate(nextProps, nextState): Allows overriding re-rendering heuristics. Returning false prevents a re-render.
• validateProps(props): (Optional) A static method to verify props. Returns true if valid, or false, "error message" if invalid. Note: This is disabled by default for performance and must be enabled via Roact.setGlobalConfig({ propValidation = true }).

Stateful components can implement lifecycle methods to respond to changes in their existence or state. These methods are ideal for side-effects like network requests, measuring UI via refs, or managing external loops.

Key lifecycle methods include:

• init: Used to initialize the component's state.
• didMount: Called after the component is created and mounted. Useful for starting loops or network requests.
• didUpdate: Called when the component's props or state change.
• willUnmount: Called immediately before the component is destroyed. Use this to clean up side-effects, such as stopping loops or disconnecting events.

By default, Roact components must return a single element via Roact.createElement. This often forces developers to wrap collections of elements in a container (like a Frame), which can break layout logic (e.g., UIListLayout not applying to children because they are nested inside an extra container).

Roact.createFragment allows a component to return a collection of elements that will be rendered as direct children of the component's parent, without adding an extra node to the Roblox hierarchy.

local function TeamLabels(props)
	return Roact.createFragment({
		RedTeam = Roact.createElement("TextLabel", {
			-- Props for item...
		}),
		BlueTeam = Roact.createElement("TextLabel", {
			-- Props for item...
		})
	})
end