createRef API

docs/advanced/refs.md

@@ -8,7 +8,59 @@
 To create a ref, pass a function prop with the key `Roact.Ref` when creating a primitive element.
 
 For example, suppose we wanted to create a search bar that captured cursor focus when any part of it was clicked. We might use a component like this:
+```lua
+--[[
+	A search bar with an icon and a text box that captures focus for its TextBox
+	when its icon is clicked
+ ]]
+local SearchBar = Roact.Component:extend("SearchBar")
+
+function SearchBar:init()
+	-- Roact.createRef creates an object reference.
+	-- This has a single property, `current`, that can be used to access the
+	-- current Roblox instance.
+	self.textBoxRef = Roact.createRef()
+end
+
+function SearchBar:captureFocus()
+	local textBox = self.textBoxRef.current
 
+	-- If we have a current instance, capture focus on it.
+	-- current will be nil if the component hasn't been mounted yet, or it's
+	-- being unmounted.
+	if textBox then
+		textBox:CaptureFocus()
+	end
+end
+
+function SearchBar:render()
+	-- Render our icon and text box side by side in a Frame
+	return Roact.createElement("Frame", {
+		Size = UDim2.new(0, 200, 0, 20),
+	}, {
+		SearchIcon = Roact.createElement("ImageButton", {
+			Size = UDim2.new(0, 20, 0, 20),
+			-- Handle click events on the icon
+			[Roact.Event.MouseButton1Click] = function()
+				self:captureFocus()
+			end,
+		}),
+
+		SearchTextBox = Roact.createElement("TextBox", {
+			Size = UDim2.new(0, 180, 0, 20),
+			Position = UDim2.new(0, 20, 0, 0),
+			-- We use Roact.Ref to get a reference to the underlying object
+			-- Roact will set textBoxRef.current to the underlying object as
+			-- part of the rendering process.
+			[Roact.Ref] = self.textBoxRef,
+		}),
+	})
+end
+```
+When a user clicks on the outer `ImageButton`, the `captureFocus` method will be called and the `TextBox` instance will get focus as if it had been clicked on directly.
+
+## Functional Refs
+Roact allows you to use functions as refs. The function will be called with the Roblox object that Roact creates. For example, this is the SearchBar component from above, modified to use functional refs instead of object refs:
 ```lua
 --[[
 	A search bar with an icon and a text box that captures focus for its TextBox
@@ -51,6 +103,7 @@ end
 When a user clicks on the outer `ImageButton`, the `captureTextboxFocus` callback will be triggered and the `TextBox` instance will get focus as if it had been clicked on directly.
 
 ## Refs During Teardown
+
 !!! warning
 	When a component instance is destroyed or the ref property changes, `nil` will be passed to the old ref function!
 

docs/api-reference.md

@@ -61,6 +61,13 @@ If `children` contains more than one child, `oneChild` function will throw an er
 
 If `children` is `nil` or contains no children, `oneChild` will return `nil`.
 
+### Roact.createRef
+```
+Roact.createRef() -> Ref
+```
+
+Creates a new reference object that can be used with [Roact.Ref](#roactref).
+
 ## Constants
 
 ### Roact.Children
@@ -72,6 +79,10 @@ If you're writing a new functional or stateful element that needs to be used lik
 Use `Roact.Ref` as a key into the props of a primitive element to receive a handle to the underlying Roblox Instance.
 
 ```lua
+Roact.createElement("Frame", {
+	[Roact.Ref] = objectReference,
+})
+
 Roact.createElement("Frame", {
 	[Roact.Ref] = function(rbx)
 		print("Roblox Instance", rbx)

lib/Reconciler.lua

@@ -44,6 +44,18 @@ local function isPortal(element)
 	return element.component == Core.Portal
 end
 
+--[[
+	Sets the value of a reference to a new rendered object.
+	Correctly handles both function-style and object-style refs.
+]]
+local function applyRef(ref, newRbx)
+	if type(ref) == "table" then
+		ref.current = newRbx
+	else
+		ref(newRbx)
+	end
+end
+
 local Reconciler = {}
 
 Reconciler._singleEventManager = SingleEventManager.new()
@@ -93,8 +105,10 @@ function Reconciler.unmount(instanceHandle)
 
 		-- Kill refs before we make changes, since any mutations past this point
 		-- aren't relevant to components.
-		if element.props[Core.Ref] then
-			element.props[Core.Ref](nil)
+		local ref = element.props[Core.Ref]
+
+		if ref then
+			applyRef(ref, nil)
 		end
 
 		for _, child in pairs(instanceHandle._children) do
@@ -173,8 +187,9 @@ function Reconciler._mountInternal(element, parent, key, context)
 		rbx.Parent = parent
 
 		-- Attach ref values, since the instance is initialized now.
-		if element.props[Core.Ref] then
-			element.props[Core.Ref](rbx)
+		local ref = element.props[Core.Ref]
+		if ref then
+			applyRef(ref, rbx)
 		end
 
 		return {
@@ -323,7 +338,7 @@ function Reconciler._reconcileInternal(instanceHandle, newElement)
 
 		-- Cancel the old ref before we make changes. Apply the new one after.
 		if refChanged and oldRef then
-			oldRef(nil)
+			applyRef(oldRef, nil)
 		end
 
 		-- Update properties and children of the Roblox object.

lib/Reconciler.spec.lua

@@ -1,8 +1,39 @@
 return function()
+	local Core = require(script.Parent.Core)
 	local Reconciler = require(script.Parent.Reconciler)
+	local createRef = require(script.Parent.createRef)
 
 	it("should mount booleans as nil", function()
 		local booleanReified = Reconciler.mount(false)
 		expect(booleanReified).to.never.be.ok()
 	end)
+
+	it("should handle object references properly", function()
+		local objectRef = createRef()
+		local element = Core.createElement("StringValue", {
+			[Core.Ref] = objectRef,
+		})
+
+		local handle = Reconciler.mount(element)
+		expect(objectRef.current).to.be.ok()
+		Reconciler.unmount(handle)
+		expect(objectRef.current).to.never.be.ok()
+	end)
+
+	it("should handle function references properly", function()
+		local currentRbx
+
+		local function ref(rbx)
+			currentRbx = rbx
+		end
+
+		local element = Core.createElement("StringValue", {
+			[Core.Ref] = ref,
+		})
+
+		local handle = Reconciler.mount(element)
+		expect(currentRbx).to.be.ok()
+		Reconciler.unmount(handle)
+		expect(currentRbx).to.never.be.ok()
+	end)
 end

lib/createRef.lua

@@ -0,0 +1,20 @@
+--[[
+	Provides an API for acquiring a reference to a reified object. This
+	API is designed to mimic React 16.3's createRef API.
+
+	See:
+	* https://reactjs.org/docs/refs-and-the-dom.html
+	* https://reactjs.org/blog/2018/03/29/react-v-16-3.html#createref-api
+]]
+
+local refMetatable = {
+	__tostring = function(self)
+		return ("RoactReference(%q)"):format(tostring(self.current))
+	end,
+}
+
+return function()
+	return setmetatable({
+		current = nil,
+	}, refMetatable)
+end

lib/createRef.spec.lua

@@ -0,0 +1,12 @@
+return function()
+	local createRef = require(script.Parent.createRef)
+
+	it("should create refs", function()
+		expect(createRef()).to.be.ok()
+	end)
+
+	it("should support tostring on refs", function()
+		local ref = createRef()
+		expect(tostring(ref)).to.equal("RoactReference(\"nil\")")
+	end)
+end

lib/init.lua

@@ -4,6 +4,7 @@
 
 local Component = require(script.Component)
 local Core = require(script.Core)
+local createRef = require(script.createRef)
 local Event = require(script.Event)
 local Change = require(script.Change)
 local GlobalConfig = require(script.GlobalConfig)
@@ -39,6 +40,7 @@ apply(Roact, ReconcilerCompat)
 
 apply(Roact, {
 	Component = Component,
+	createRef = createRef,
 	PureComponent = PureComponent,
 	Event = Event,
 	Change = Change,

lib/init.spec.lua

@@ -4,6 +4,7 @@ return function()
 	it("should load with all public APIs", function()
 		local publicApi = {
 			createElement = "function",
+			createRef = "function",
 			mount = "function",
 			unmount = "function",
 			reconcile = "function",