react-luau ports React 17 to Luau for Roblox UI work

React's ideas, translated rather than ported

React Luau is described as a comprehensive, but not exhaustive, translation of ReactJS 17.x into Luau, and the README calls it a declarative library for building user interfaces and a highly-tuned translation of React that is currently based on React 17. The word translation is doing deliberate work in that sentence. A port would try to make Luau look like JavaScript; a translation keeps React's concepts and re-expresses them in the idioms of the target language, which is why the README then explains where the two diverge. The two properties the project leads with are the ones React is known for. It is declarative, so you design simple views for each state and React updates and renders the right components when data changes, which the documentation argues makes code more predictable, simpler to understand and easier to debug. It is component based, so you build encapsulated components that manage their own state and compose them, and because component logic is written in Luau instead of being managed through Roblox's Instances, you can pass rich data through your code and keep state out of the data model. The site is react-luau.dev, and the repository carries a Packages/ directory, a mkdocs.yml, a rotriever.toml, multipack.toml and a foreman.toml, so several Roblox package tooling paths are supported at once.

Bindings: signals that skip the re-render

The third property is the one that makes this a Roblox library rather than a straight translation, and it is worth reading closely. The project states that Luau is not Javascript, so they deviate from ReactJS in certain places for a more ergonomic programming experience in Luau and with Roblox's wider programming model. The example given is Bindings, a form of signals-based state that does not re-render, for highly-efficient animations driven by React. That is a substantial departure from React's model, where a state change re-renders a component and the diff is what makes it cheap. Here the signal updates without the component tree being re-rendered, which for a Roblox UI means an animation can drive an instance property directly rather than going through a reconciliation pass. The cost is that two different mental models now coexist in one codebase, and a developer has to know which of them a given piece of state belongs to. A property changed through a Binding is not the same as a property changed through React state, and the README does not describe a rule for choosing between them. In practice that judgement is left to the developer, and it is the main thing to understand before writing anything substantial with this library.

The first example, and what it shows about the API

The README gives one worked example and says it renders a greeting into a TextLabel on the screen. It is short, and every line of it teaches something about the shape of the API.

local React = require(Packages.React)
local ReactRoblox = require(Packages.ReactRoblox)

local e = React.createElement

local function HelloMessage(props: {
	name: string,
})
	return e("TextLabel", {
		AnchorPoint = Vector2.new(0.5, 0.5),
		Position = UDim2.fromScale(0.5, 0.5),
		AutomaticSize = Enum.AutomaticSize.XY,
		Text = `Hello, {props.name}!`,
	})
end

local function App()
	return e("ScreenGui", {}, {
		MyMessage = e(HelloMessage, {
			name = "Taylor",
		}),
	})
end

local root = ReactRoblox.createRoot(Instance.new("Folder"))
root:render(ReactRoblox.createPortal(e(App), Players.LocalPlayer.PlayerGui))

Three conventions show up immediately. Elements are created with a function rather than with JSX, and the createElement call is aliased to e for readability. Props are plain Luau, with a typed table for the props argument, so the type checker participates in the component contract. And the Roblox specific part is separate from the React part: ReactRoblox provides createRoot and createPortal, and the tree is mounted into Players.LocalPlayer.PlayerGui, so a client-side UI lands in the player's interface. The ScreenGui element is created inside the component and its children are passed as the third argument, which is React's children convention.

Distribution through the Creator Store and Wally

There is no npm install here, and the way you get this library into a project is specific to Roblox. The README carries a link to the Creator Store at create.roblox.com, and a separate link to Wally pointing at the roblox/react package, and the instruction about the download and install is enclosed in an HTML comment in the source, which suggests the installation section is still being reorganised. The documentation itself lives on the website at react-luau.dev, and the README points there with a link labelled as how to use React Luau in your project, plus a link to several examples on the same site. The repository layout backs up the multi-tooling picture. There is a default.project.json and a tests.project.json, which are the Roblox Studio project files, and a WorkspaceStatic/ directory alongside a Packages/ directory for the package contents. The js-to-lua.config.js file at the root is the interesting one, because it suggests the translation is not entirely hand written but partly produced by a conversion step from the original JavaScript source, with the configuration driving how the conversion behaves. For a user, the practical point is that you are consuming a package inside Roblox's own ecosystem, not a dependency in a Node project, so the familiar npm workflow does not apply.

Tooling around the code, and the signals of a real project

Even though the library is a translation, the repository is a full project with a proper engineering setup, and the files show it. There is a selene.toml for the Selene linter, a stylua.toml and a .styluaignore for StyLua formatting, an .editorconfig, CODE_OF_CONDUCT.md, a codecov.yml, a bin/ directory, a docs/ directory and an assets/ directory holding the logo. A tests.project.json alongside default.project.json means the test suite runs in Roblox Studio rather than in a plain Node runner, which is a constraint on how contributors work. The README badges point at a tests workflow and a coveralls coverage status, and the coverage link carries a token in its query string, which tells you the coverage reporting is wired to a specific account rather than a generic service. The version history is short and informative. The only listed release is v17.0.1 dated 2024-01-18, and the version number is the React version it tracks, which is a convention that makes the library's compatibility legible at a glance but also means the numbering will not move unless the underlying React version does. The last push to the repository was on 2026-10-14, so the tree is still being worked on even though the tagged release is older.

Where react-luau is the wrong choice

The boundaries are clear from the project's own framing. The first is React version coverage. The library is based on React 17, and the description calls the translation comprehensive but not exhaustive, so anything you reach for in modern React is outside what this package provides. If your mental model of React comes from a recent tutorial, the API surface here will not match what you expect. The second is that a translation carries the cost of the original's compromises plus the cost of the translation. React itself was written for a browser DOM with a synchronous renderer, and the project acknowledges it deviates in several places to be more ergonomic in Luau. That is the right call for a Roblox developer and it means the library is not a reference implementation of React semantics, so a developer who knows React deeply will find places where the behaviour differs and will need to learn the deviations rather than assume them. The third is the platform itself. Luau and Roblox Instances are a different object model from the DOM, and while the component model translates, anything that depends on browser specific behaviour, the DOM, or a React ecosystem package does not come with it. If your work is a web app, this library is the wrong direction entirely, and if it is a Roblox app with a large existing team already fluent in Roblox UI patterns, the migration cost deserves its own estimate.

Editorial conclusion

Adopt react-luau if you build Roblox interfaces and want React's declarative component model in Luau, especially if your work involves animation, where the Bindings extension is the reason to pick this over hand written instance manipulation. Do not adopt it if you need modern React features, because the library is based on React 17 and the translation is described as comprehensive but not exhaustive, so newer hooks and concurrent rendering ideas are not part of what you get. Verify two things before you commit: that the package you install is the one you expect, since the project description labels this repository a read-only mirror and the distribution runs through the Creator Store and Wally rather than through a package manager you already use, and that the examples on the website match the API version you will actually get. The practical first step is to install the package from the Creator Store or Wally, then run the Hello Message example below to see a TextLabel render into the local player's PlayerGui before writing your own components.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. Roblox/react-luau on GitHub