Skip to main content

ReactObservableValue

React hooks for ObservableValue: read a value and rerender, select part of it, or follow it with a binding.

Functions​

useObservableValue​

</>
ReactObservableValue.useObservableValue(source: ObservableValue<T>) → (
T,--

the current value

number--

increases every time the value changes

)

Returns the ObservableValue’s current value, and rerenders the component whenever it changes. The second return value increases on every change so it can be used as a useMemo / useEffect dependency even when a table was changed in place. 

local function HealthBar(props: { health: ObservableValue.ObservableValue<number> })
	local health = ReactObservableValue.useObservableValue(props.health)
	return React.createElement("TextLabel", { Text = `{health} HP` })
end

useObservableBinding​

</>
ReactObservableValue.useObservableBinding(source: ObservableValue<T>) → Binding<T>

Returns a React binding that follows the ObservableValue without rerendering the component. Bindings update instance properties directly, which suits values that change often, like progress bars and timers. Use the binding's map to turn the value into a property. 

local function ProgressBar(props: { progress: ObservableValue.ObservableValue<number> })
	local progress = ReactObservableValue.useObservableBinding(props.progress)
	return React.createElement("Frame", {
		Size = progress:map(function(value)
			return UDim2.fromScale(value, 1)
		end),
	})
end

useObservableSelector​

</>
ReactObservableValue.useObservableSelector(
source: ObservableValue<T>,
selector: (value: T) → U,
isEqual: ((
previous: U,
current: U
) → boolean)?
) → U

Returns selector(value) and rerenders the component only when that result changes, not on every change to the ObservableValue. Use it to read part of a table, or something computed from the value.

Results are compared with == unless you pass isEqual. A selector that builds a new table each time needs an isEqual, or it rerenders on every change. 

local function BlurOverlay(props: { blurStack: ObservableValue.ObservableValue<{ [number]: true }> })
	local isVisible = ReactObservableValue.useObservableSelector(props.blurStack, function(stack)
		return next(stack) ~= nil
	end)
	return React.createElement("Frame", { Visible = isVisible })
end
Show raw api
{
    "functions": [
        {
            "name": "useObservableValue",
            "desc": "Returns the ObservableValue’s current value, and rerenders the component whenever it changes. The second return value\nincreases on every change so it can be used as a `useMemo` / `useEffect` dependency even when a table was\nchanged in place.\n\n```lua\nlocal function HealthBar(props: { health: ObservableValue.ObservableValue<number> })\n\tlocal health = ReactObservableValue.useObservableValue(props.health)\n\treturn React.createElement(\"TextLabel\", { Text = `{health} HP` })\nend\n```",
            "params": [
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "ObservableValue<T>"
                }
            ],
            "returns": [
                {
                    "desc": "the current value",
                    "lua_type": "T"
                },
                {
                    "desc": "increases every time the value changes",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 31,
                "path": "src/init.luau"
            }
        },
        {
            "name": "useObservableBinding",
            "desc": "Returns a React binding that follows the ObservableValue without rerendering the component. Bindings update\ninstance properties directly, which suits values that change often, like progress bars and timers. Use the\nbinding's `map` to turn the value into a property.\n\n```lua\nlocal function ProgressBar(props: { progress: ObservableValue.ObservableValue<number> })\n\tlocal progress = ReactObservableValue.useObservableBinding(props.progress)\n\treturn React.createElement(\"Frame\", {\n\t\tSize = progress:map(function(value)\n\t\t\treturn UDim2.fromScale(value, 1)\n\t\tend),\n\t})\nend\n```",
            "params": [
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "ObservableValue<T>"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Binding<T>"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 74,
                "path": "src/init.luau"
            }
        },
        {
            "name": "useObservableSelector",
            "desc": "Returns `selector(value)` and rerenders the component only when that result changes, not on every change to the\nObservableValue. Use it to read part of a table, or something computed from the value.\n\nResults are compared with `==` unless you pass `isEqual`. A selector that builds a new table each time needs an\n`isEqual`, or it rerenders on every change.\n\n```lua\nlocal function BlurOverlay(props: { blurStack: ObservableValue.ObservableValue<{ [number]: true }> })\n\tlocal isVisible = ReactObservableValue.useObservableSelector(props.blurStack, function(stack)\n\t\treturn next(stack) ~= nil\n\tend)\n\treturn React.createElement(\"Frame\", { Visible = isVisible })\nend\n```",
            "params": [
                {
                    "name": "source",
                    "desc": "",
                    "lua_type": "ObservableValue<T>"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "(value: T) -> U"
                },
                {
                    "name": "isEqual",
                    "desc": "",
                    "lua_type": "((previous: U, current: U) -> boolean)?"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "U"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 109,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "ReactObservableValue",
    "desc": "React hooks for [ObservableValue](https://jdevon.github.io/observable-value/): read a value and rerender, select part of\nit, or follow it with a binding.",
    "source": {
        "line": 11,
        "path": "src/init.luau"
    }
}