Recreate Docs

Recreate is a very simple library, its so simple we can teach you the entire library in one page. The repository also contains RTK, Recreate Toolkit, which are two very useful utility libraries for getting up and started with Recreate state.

Basic Recreate Usage

Recreate at its core is derived from the old RBXUtility feature, Create, although there are a few syntatical changes which we'll note as we go along.

The basic constructor: Recreate.Create

If you just want to create Instances, you can do so with Create:

local node = Recreate.Create("Frame", {
	AnchorPoint = Vector2.new(0.5,0.5),
	AutomaticSize = "XY",
	BackgroundColor3 = Color3.fromRGB(255, 170, 0)
	BorderSizePixel = 0,
	Size = UDim2.fromOffset(100, 100)
})

This returns a Node, which we'll explain more about when we get to Recreate's State Model (or should we say, lack of one), to set the parent, use SetParent:

info

Almost everything with Recreate will return the Node, not the Instance, the Instance can be accessed through .Instance, however, this is intended for state engines to work with, not live code.

node:SetParent(script.Parent) -- assuming the parent is a LayerCollector

Events

Events can be defined by directly passing a function to it, all events give you a struct known as a SenderParams, which contains the calling Node and Connection.

local node = Recreate.Create("TextButton", {
	Activated = function(sp, _, timesClicked)
		print("hi Recreate!", timesClicked)
	end
})

Children

Children can be defined with the Children key, which should be more Nodes that get parented to this Node automatically

Recreate.Create("Frame", {
	AnchorPoint = Vector2.new(0.5,0.5),
	AutomaticSize = "XY",
	BackgroundColor3 = Color3.fromRGB(255, 170, 0)
	BorderSizePixel = 0,
	Size = UDim2.fromOffset(100, 100),

	Children = {
		Recreate.Create("TextButton", {
			Activated = function(sp, _, timesClicked)
				print("hi Recreate!", timesClicked)
			end
		})
	}
})

tip

It'll become more obvious why Children is handled this way, when you get to State.

Change Events

Change Events work similarly to regular events, except you need to use the SpecialKey to tell Recreate that you want to bind a change event:

Recreate.Create("TextBox", {
	Text = "Hello Recreate!",
	[Recreate.Change "Text"] = function(sp, propName, newValue)
		print(newValue)
	end
})

Stylesheet Classes

Recreate was made with Stylesheets in mind, for this, defining them is trivial, just add Class to your property definition.

Recreate.Create("Frame", {
	Class = { "bg-frame-1" }
})

Templating: Recreate.FromTemplate

Another common usecase with UI is to create a template, then :Clone it as you use it. Recreate supports this workflow! You can create templates using FromTemplate:

This method can still take the prop table, which is useful if you want to bind state logic or events:

Recreate.FromTemplate(ReplicatedStorage.Templates.Button, {
	MouseButton1Click = function(sp)
		...
	end
})

warning

FromTemplate uses Instance.fromExisting, which does not clone Children, you must explicitly define these if you want them to persist within your tree.

Recreate does not support Template instances inside each other, create seperate templates and construct your tree that way.

Recreate.FromExisting

For some objects, most notably, DockWidgetPluginGui, you cant create them with the Instance constructors. For this, we have FromExisting, which will create a Node from an existing object.

Much like the others, you can still bind extra logic to the Node.

local dockWidget = plugin:CreateDockWidgetPluginGui("the-widget", DockWidgetPluginGuiInfo.new())
Recreate.FromExisting(dockWidget)

danger

This method can introduce sneaky runtime bugs and should only be used in the cases where it's needed. If you have Instances that can be cloned, use FromTemplate.

Components

Components in Recreate are extremely simple. The constructor takes a function, then returns a function to build a new node from given properties.

return Recreate.Component("that one", function(props)
	return Recreate.Create("Frame", {

	})
end)

return Recreate.Create("Frame", {
	Children = {
		theCoolestComponent {}
	}
})

This method should return a node, Components can return other Components, where it will then override the FactoryName property to the one of the most recent factory.

Watchables

Now onto Recreate's coolest part, its state model, or lack of one. It might seem weird that a UI library would ship without State, but Recreate can do one better, letting you define the state model instead, with something known as Watchables

Watchables are any object that have a well-defined __RCImplementor tag.

tip

RTK contains Logica, a highly optimised state library, and WatchedList, which simplifies working with Children and Class states

For this part of the documentation, we'll use parts of code from RTK, however, you can and are completely free to use whatever you want when it comes to defining state

Using Watchables

You can pass Watchables directly to any property rather than the property itself, which binds it to that Watchable's backend handler.

local text = Logica.Node("clicked 0")

Recreate.Create("TextButton", {
	Text = text,
	Activated = function(sp, _, timesClicked)
		text:set(timesClicked)
	end
})

Additionally, you can even bind Children and Class to a Watchable, to get dynamic handling of those two properties.

local children = WatchedList.new()

Recreate.Create("Frame", {
	Children = children
})

Creating Watchables

A Watchable is considered Watchable when it defines an __RCImplementor, for more info on how to use thse, refer to the API documentation.