Skip to main content

Hooks

A collection of hooks made for React.

Functions​

useAsync​

State Management
</>
Hooks.useAsync(
promiseOrGetPromise: Promise<T> | () → Promise<T>,--

The Promise to wrap.

dependencies: {unknown}?
) → (
T?,--

The result of the Promise.

unknown?,--

The error message of the Promise.

Promise.Status--

The status of the Promise.

)

useAsync wraps a Promise to a state.

info

Taken from here

useClickOutside​

This item only works when running on the client. ClientUser Interface
</>
Hooks.useClickOutside(
onClick: () → (),--

A callback to call when a click or touch event is detected outside of the element.

userInputTypes?: {Enum.UserInputType},--

A list of user input types to detect. Defaults to Enum.UserInputType.MouseButton1 and Enum.UserInputType.Touch.

guiObjects?: {GuiObject}--

A list of elements to detect clicks outside of. Defaults to the element returned by useRef.

) → Ref<GuiObject>--

A ref to the element to detect clicks outside of.

A hook used to detect click and touch events outside of specified element.

Luau:

local function Component()
	local visible, setVisible = React.useBinding(false)
	local ref = Hooks.useClickOutside(function()
		setVisible(false)
	end)

	return React.createElement("Frame", {
		AnchorPoint = Vector2.new(0.5, 0.5),
		BackgroundColor3 = Color3.fromRGB(255, 255, 255),
		BorderSizePixel = 0,
		Position = UDim2.fromScale(0.5, 0.5),
		Size = UDim2.fromOffset(100, 100),
		Visible = visible,

		ref = ref,
	})
end

useCurrentCamera​

This item only works when running on the client. Client
</>
Hooks.useCurrentCamera(
onChange?: (currentCamera: Camera) → ()--

A callback that is called when the current camera changes.

) → Camera--

The current camera.

A hook used for getting the current camera.

useDelayedValue​

State Management
</>
Hooks.useDelayedValue(
value: T,--

The value to delay.

delayInSeconds: number--

The amount of time to delay the value by.

) → T--

The delayed value.

A hook used for delaying a value.

useExternalEvent​

Lifecycle
</>
Hooks.useExternalEvent(
event: RBXScriptSignal,--

The event to connect to.

callback: (...any) → ()--

The callback to connect to the event.

) → ()

A hook that connects and disconnects a callback to an event. This is really just a fancy useEffect wrapper.

Luau:

local function Component()
end

useForceUpdate​

Lifecycle
</>
Hooks.useForceUpdate() → () → ()--

The function to call to force a re-render.

A hook that creates a function used to force a component to re-render.

useId​

State Management
</>
Hooks.useId(
staticId?: string--

A static id to use instead of a generated one.

) → string--

The generated id.

The useId hook generates random id that persists across renders. Hook is usually used to bind input elements to labels. Generated random id is saved to ref and will not change unless component is unmounted.

useMemoWithCleanup​

State Management
</>
Hooks.useMemoWithCleanup(
createValue: () → T,--

The function to create the value.

cleanupValue: (value: T) → (),--

The function to clean up the value.

dependencies?: {unknown}--

The dependencies to check for changes.

) → T--

The memoized value.

A hook that memoizes a value and cleans it up when the dependencies change.

usePrevious​

State Management
</>
Hooks.usePrevious(
value: T--

The value to store.

) → T?--

The previous value of the state.

The usePrevious hook stores the previous value of a state in a ref, it returns undefined on initial render and the previous value of a state after rerender.

useRainbowColorSequence​

UIEffects
</>
Hooks.useRainbowColorSequence(
parameters?: IParameters--

The parameters for the hook.

) → Binding<ColorSequence>--

The rainbow color sequence.

An example hook that uses a rainbow color sequence.

useRendersSpy​

LifecycleDebugging
</>
Hooks.useRendersSpy() → number--

The amount of renders.

Returns the amount of times the component has been rendered since mounting. This is a very useful hook for testing.

useScale​

This item only works when running on the client. ClientUI
</>
Hooks.useScale(
scale: number,--

The scale to use for the UI element.

goalSize: Vector2 | Vector3--

The size of the UI element. Recommended to use Vector3 as it is faster.

) → Binding<number>--

The scale to use for the UI element.

A hook used for scaling UI elements to fit the current screen.

useShallowEffect​

Lifecycle
</>
Hooks.useShallowEffect(
callback: () → (),--

The callback to run when the dependencies change.

dependencies?: {unknown}--

The dependencies to compare.

) → ()

useEffect drop in replacement with dependencies shallow comparison. useShallowEffect works exactly like useEffect but performs shallow dependencies comparison instead of referential comparison.

useStrokeScale​

This item only works when running on the client. ClientUIEffects
</>
Hooks.useStrokeScale(
pixelThickness?: number,--

The thickness of the stroke in pixels. Defaults to 1.

relativeSize?: number--

The relative size of the screen. Defaults to 985.

) → Binding<number>--

The thickness of the stroke in pixels.

A hook used to scale a stroke size based on the viewport size.

useSyncExternalStore​

Polyfill
</>
Hooks.useSyncExternalStore(
subscribe: (onStoreChange: () → ()) → () → (),--

A function that subscribes to the external store.

getSnapshot: () → Snapshot--

A function that returns the current snapshot of the external store.

) → Snapshot--

The current snapshot of the external store.

A polyfill for React 18's useSyncExternalStore hook.

info

For more info, check out the issue on the React 18 Working Group.

useSyncExternalStoreWithSelector​

Polyfill
</>
Hooks.useSyncExternalStoreWithSelector(
subscribe: (onStoreChange: () → ()) → () → (),--

A function that subscribes to the external store.

getSnapshot: () → Snapshot,--

A function that returns the current snapshot of the external store.

selector: (snapshot: Snapshot) → Selected,--

A selector function that is used to select a value from the snapshot.

isEqual?: (
left: Selected,
right: Selected
) → boolean--

A function used to determine if the selected value has changed.

) → Selected--

The selected value for the current snapshot of the external store.

A polyfill for React 18's useSyncExternalStore hook that allows for a selector.

info

For more info, check out the issue on the React 18 Working Group.

useTheme​

This item only works when running in the context of a plugin. Plugin
</>
Hooks.useTheme() → ThemeData--

The current theme.

A hook that returns the current theme. Used for Plugins.

useUncontrolled​

State Management
</>
Hooks.useUncontrolled(
input?: IUseUncontrolledInput<T>--

The input to use.

) → (
T,--

The value to use.

(value: T) → (),--

The onChange handler to use.

boolean--

Whether the component is controlled or not.

)

Manage state of both controlled and uncontrolled components.

useViewportSize​

This item only works when running on the client. Client
</>
Hooks.useViewportSize(
onChange?: (viewportSize: Vector2) → ()--

A callback that is called when the viewport size changes.

) → Binding<Vector2>--

The current viewport size.

A hook that returns the current ViewportSize of the CurrentCamera.

useWhyDidYouUpdate​

Debug
</>
Hooks.useWhyDidYouUpdate(
name: string,--

The name of the component.

props: table--

The props of the component.

) → ()

Quickly see which prop changed and caused a re-render by adding a single line to the component.

Show raw api
{
    "functions": [
        {
            "name": "useAsync",
            "desc": "`useAsync` wraps a Promise to a state.\n\n:::info\nTaken from [here](https://github.com/littensy/roact-hooked-plus/blob/master/src/use-promise.ts)\n:::",
            "params": [
                {
                    "name": "promiseOrGetPromise",
                    "desc": "The Promise to wrap.",
                    "lua_type": "Promise<T> | () -> Promise<T>"
                },
                {
                    "name": "dependencies",
                    "desc": "",
                    "lua_type": "{unknown}?"
                }
            ],
            "returns": [
                {
                    "desc": "The result of the Promise.",
                    "lua_type": "T?"
                },
                {
                    "desc": "The error message of the Promise.",
                    "lua_type": "unknown?"
                },
                {
                    "desc": "The status of the Promise.",
                    "lua_type": "Promise.Status"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 26,
                "path": "src/useAsync.lua"
            }
        },
        {
            "name": "useClickOutside",
            "desc": "A hook used to detect click and touch events outside of specified element.\n\n### Luau:\n\n```lua\nlocal function Component()\n\tlocal visible, setVisible = React.useBinding(false)\n\tlocal ref = Hooks.useClickOutside(function()\n\t\tsetVisible(false)\n\tend)\n\n\treturn React.createElement(\"Frame\", {\n\t\tAnchorPoint = Vector2.new(0.5, 0.5),\n\t\tBackgroundColor3 = Color3.fromRGB(255, 255, 255),\n\t\tBorderSizePixel = 0,\n\t\tPosition = UDim2.fromScale(0.5, 0.5),\n\t\tSize = UDim2.fromOffset(100, 100),\n\t\tVisible = visible,\n\n\t\tref = ref,\n\t})\nend\n```",
            "params": [
                {
                    "name": "onClick",
                    "desc": "A callback to call when a click or touch event is detected outside of the element.",
                    "lua_type": "() -> ()"
                },
                {
                    "name": "userInputTypes?",
                    "desc": "A list of user input types to detect. Defaults to `Enum.UserInputType.MouseButton1` and `Enum.UserInputType.Touch`.",
                    "lua_type": "{Enum.UserInputType}"
                },
                {
                    "name": "guiObjects?",
                    "desc": "A list of elements to detect clicks outside of. Defaults to the element returned by `useRef`.",
                    "lua_type": "{GuiObject}"
                }
            ],
            "returns": [
                {
                    "desc": "A ref to the element to detect clicks outside of.",
                    "lua_type": "Ref<GuiObject>"
                }
            ],
            "function_type": "static",
            "tags": [
                "User Interface"
            ],
            "realm": [
                "Client"
            ],
            "source": {
                "line": 55,
                "path": "src/useClickOutside.lua"
            }
        },
        {
            "name": "useCurrentCamera",
            "desc": "A hook used for getting the current camera.",
            "params": [
                {
                    "name": "onChange?",
                    "desc": "A callback that is called when the current camera changes.",
                    "lua_type": "(currentCamera: Camera) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "The current camera.",
                    "lua_type": "Camera"
                }
            ],
            "function_type": "static",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 16,
                "path": "src/useCurrentCamera.lua"
            }
        },
        {
            "name": "useDelayedValue",
            "desc": "A hook used for delaying a value.",
            "params": [
                {
                    "name": "value",
                    "desc": "The value to delay.",
                    "lua_type": "T"
                },
                {
                    "name": "delayInSeconds",
                    "desc": "The amount of time to delay the value by.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The delayed value.",
                    "lua_type": "T"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 31,
                "path": "src/useDelayedValue.lua"
            }
        },
        {
            "name": "useExternalEvent",
            "desc": "A hook that connects and disconnects a callback to an event. This is really\njust a fancy `useEffect` wrapper.\n\n### Luau:\n\n```lua\nlocal function Component()\nend\n```",
            "params": [
                {
                    "name": "event",
                    "desc": "The event to connect to.",
                    "lua_type": "RBXScriptSignal"
                },
                {
                    "name": "callback",
                    "desc": "The callback to connect to the event.",
                    "lua_type": "(...any) -> ()"
                }
            ],
            "returns": [],
            "function_type": "static",
            "tags": [
                "Lifecycle"
            ],
            "source": {
                "line": 22,
                "path": "src/useExternalEvent.lua"
            }
        },
        {
            "name": "useForceUpdate",
            "desc": "A hook that creates a function used to force a component to re-render.",
            "params": [],
            "returns": [
                {
                    "desc": "The function to call to force a re-render.",
                    "lua_type": "() -> ()"
                }
            ],
            "function_type": "static",
            "tags": [
                "Lifecycle"
            ],
            "source": {
                "line": 16,
                "path": "src/useForceUpdate.lua"
            }
        },
        {
            "name": "useId",
            "desc": "The `useId` hook generates random id that persists across renders. Hook is usually used to bind input elements to labels. Generated random id is saved to ref and will not change unless component is unmounted.",
            "params": [
                {
                    "name": "staticId?",
                    "desc": "A static id to use instead of a generated one.",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "The generated id.",
                    "lua_type": "string"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 14,
                "path": "src/useId.lua"
            }
        },
        {
            "name": "useMemoWithCleanup",
            "desc": "A hook that memoizes a value and cleans it up when the dependencies change.",
            "params": [
                {
                    "name": "createValue",
                    "desc": "The function to create the value.",
                    "lua_type": "() -> T"
                },
                {
                    "name": "cleanupValue",
                    "desc": "The function to clean up the value.",
                    "lua_type": "(value: T) -> ()"
                },
                {
                    "name": "dependencies?",
                    "desc": "The dependencies to check for changes.",
                    "lua_type": "{unknown}"
                }
            ],
            "returns": [
                {
                    "desc": "The memoized value.",
                    "lua_type": "T"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 20,
                "path": "src/useMemoWithCleanup.lua"
            }
        },
        {
            "name": "usePrevious",
            "desc": "The `usePrevious` hook stores the previous value of a state in a ref, it returns undefined on initial render and the previous value of a state after rerender.",
            "params": [
                {
                    "name": "value",
                    "desc": "The value to store.",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "The previous value of the state.",
                    "lua_type": "T?"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 14,
                "path": "src/usePrevious.lua"
            }
        },
        {
            "name": "useRainbowColorSequence",
            "desc": "An example hook that uses a rainbow color sequence.",
            "params": [
                {
                    "name": "parameters?",
                    "desc": "The parameters for the hook.",
                    "lua_type": "IParameters"
                }
            ],
            "returns": [
                {
                    "desc": "The rainbow color sequence.",
                    "lua_type": "Binding<ColorSequence>"
                }
            ],
            "function_type": "static",
            "tags": [
                "UI",
                "Effects"
            ],
            "source": {
                "line": 42,
                "path": "src/useRainbowColorSequence.lua"
            }
        },
        {
            "name": "useRendersSpy",
            "desc": "Returns the amount of times the component has been rendered since mounting. This is a very useful hook for testing.",
            "params": [],
            "returns": [
                {
                    "desc": "The amount of renders.",
                    "lua_type": "number"
                }
            ],
            "function_type": "static",
            "tags": [
                "Lifecycle",
                "Debugging"
            ],
            "source": {
                "line": 13,
                "path": "src/useRendersSpy.lua"
            }
        },
        {
            "name": "useScale",
            "desc": "A hook used for scaling UI elements to fit the current screen.",
            "params": [
                {
                    "name": "scale",
                    "desc": "The scale to use for the UI element.",
                    "lua_type": "number"
                },
                {
                    "name": "goalSize",
                    "desc": "The size of the UI element. Recommended to use Vector3 as it is faster.",
                    "lua_type": "Vector2 | Vector3"
                }
            ],
            "returns": [
                {
                    "desc": "The scale to use for the UI element.",
                    "lua_type": "Binding<number>"
                }
            ],
            "function_type": "static",
            "tags": [
                "UI"
            ],
            "realm": [
                "Client"
            ],
            "source": {
                "line": 18,
                "path": "src/useScale.lua"
            }
        },
        {
            "name": "useShallowEffect",
            "desc": "`useEffect` drop in replacement with dependencies shallow comparison. `useShallowEffect` works\nexactly like `useEffect` but performs shallow dependencies comparison instead of referential comparison.",
            "params": [
                {
                    "name": "callback",
                    "desc": "The callback to run when the dependencies change.",
                    "lua_type": "() -> ()"
                },
                {
                    "name": "dependencies?",
                    "desc": "The dependencies to compare.",
                    "lua_type": "{unknown}"
                }
            ],
            "returns": [],
            "function_type": "static",
            "tags": [
                "Lifecycle"
            ],
            "source": {
                "line": 52,
                "path": "src/useShallowEffect.lua"
            }
        },
        {
            "name": "useStrokeScale",
            "desc": "A hook used to scale a stroke size based on the viewport size.",
            "params": [
                {
                    "name": "pixelThickness?",
                    "desc": "The thickness of the stroke in pixels. Defaults to 1.",
                    "lua_type": "number"
                },
                {
                    "name": "relativeSize?",
                    "desc": "The relative size of the screen. Defaults to 985.",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "The thickness of the stroke in pixels.",
                    "lua_type": "Binding<number>"
                }
            ],
            "function_type": "static",
            "tags": [
                "UI",
                "Effects"
            ],
            "realm": [
                "Client"
            ],
            "source": {
                "line": 17,
                "path": "src/useStrokeScale.lua"
            }
        },
        {
            "name": "useSyncExternalStore",
            "desc": "A polyfill for React 18's `useSyncExternalStore` hook.\n\n:::info\nFor more info, check out the [issue](https://github.com/reactwg/react-18/discussions/86) on the React 18 Working Group.\n:::",
            "params": [
                {
                    "name": "subscribe",
                    "desc": "A function that subscribes to the external store.",
                    "lua_type": "(onStoreChange: () -> ()) -> () -> ()"
                },
                {
                    "name": "getSnapshot",
                    "desc": "A function that returns the current snapshot of the external store.",
                    "lua_type": "() -> Snapshot"
                }
            ],
            "returns": [
                {
                    "desc": "The current snapshot of the external store.",
                    "lua_type": "Snapshot"
                }
            ],
            "function_type": "static",
            "tags": [
                "Polyfill"
            ],
            "source": {
                "line": 49,
                "path": "src/useSyncExternalStore.lua"
            }
        },
        {
            "name": "useSyncExternalStoreWithSelector",
            "desc": "A polyfill for React 18's `useSyncExternalStore` hook that allows for a selector.\n\n:::info\nFor more info, check out the [issue](https://github.com/reactwg/react-18/discussions/86) on the React 18 Working Group.\n:::",
            "params": [
                {
                    "name": "subscribe",
                    "desc": "A function that subscribes to the external store.",
                    "lua_type": "(onStoreChange: () -> ()) -> () -> ()"
                },
                {
                    "name": "getSnapshot",
                    "desc": "A function that returns the current snapshot of the external store.",
                    "lua_type": "() -> Snapshot"
                },
                {
                    "name": "selector",
                    "desc": "A selector function that is used to select a value from the snapshot.",
                    "lua_type": "(snapshot: Snapshot) -> Selected"
                },
                {
                    "name": "isEqual?",
                    "desc": "A function used to determine if the selected value has changed.",
                    "lua_type": "(left: Selected, right: Selected) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "The selected value for the current snapshot of the external store.",
                    "lua_type": "Selected"
                }
            ],
            "function_type": "static",
            "tags": [
                "Polyfill"
            ],
            "source": {
                "line": 37,
                "path": "src/useSyncExternalStoreWithSelector.lua"
            }
        },
        {
            "name": "useTheme",
            "desc": "A hook that returns the current theme. Used for Plugins.",
            "params": [],
            "returns": [
                {
                    "desc": "The current theme.",
                    "lua_type": "ThemeData"
                }
            ],
            "function_type": "static",
            "realm": [
                "Plugin"
            ],
            "source": {
                "line": 16,
                "path": "src/useTheme.lua"
            }
        },
        {
            "name": "useUncontrolled",
            "desc": "Manage state of both controlled and uncontrolled components.",
            "params": [
                {
                    "name": "input?",
                    "desc": "The input to use.",
                    "lua_type": "IUseUncontrolledInput<T>"
                }
            ],
            "returns": [
                {
                    "desc": "The value to use.",
                    "lua_type": "T"
                },
                {
                    "desc": "The onChange handler to use.",
                    "lua_type": "(value: T) -> ()"
                },
                {
                    "desc": "Whether the component is controlled or not.",
                    "lua_type": "boolean"
                }
            ],
            "function_type": "static",
            "tags": [
                "State Management"
            ],
            "source": {
                "line": 40,
                "path": "src/useUncontrolled.lua"
            }
        },
        {
            "name": "useViewportSize",
            "desc": "A hook that returns the current ViewportSize of the CurrentCamera.",
            "params": [
                {
                    "name": "onChange?",
                    "desc": "A callback that is called when the viewport size changes.",
                    "lua_type": "(viewportSize: Vector2) -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "The current viewport size.",
                    "lua_type": "Binding<Vector2>"
                }
            ],
            "function_type": "static",
            "realm": [
                "Client"
            ],
            "source": {
                "line": 15,
                "path": "src/useViewportSize.lua"
            }
        },
        {
            "name": "useWhyDidYouUpdate",
            "desc": "Quickly see which prop changed and caused a re-render by adding a single line to the component.",
            "params": [
                {
                    "name": "name",
                    "desc": "The name of the component.",
                    "lua_type": "string"
                },
                {
                    "name": "props",
                    "desc": "The props of the component.",
                    "lua_type": "table"
                }
            ],
            "returns": [],
            "function_type": "static",
            "tags": [
                "Debug"
            ],
            "source": {
                "line": 20,
                "path": "src/useWhyDidYouUpdate.lua"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Hooks",
    "desc": "A collection of hooks made for React.",
    "source": {
        "line": 36,
        "path": "src/init.lua"
    }
}