Hooks

Functions

useArray

</>

Hooks.useArray(initialValue: {T} | nil) → HookCreator<UseArray<T>>

Types

interface UseArray<T> {

array: {T}

set: (valueOrCallback: T | (array: T) → T) → void

push: (...elements: T) → void

filter: (callback: (

element: T,

index: number

) → boolean) → void

update: (

index: number,

element: T

) → void

remove: (index: number) → void

clear: () → void

}

Lets you manipulate an array data structure without ever needing extra utilities.

local function HookedComponent(props, hooks)
        local text = hooks.useValue()
        local list = useArray({})(hooks)

        return Roact.createFragment({
                Button = Roact.createElement("TextButton", {
                        -- ...
                        Text = "Add",
                        [Roact.Event.MouseButton1Click] = function(rbx)
                                if text.value then
                                        list.push(text.value)
                                end
                                text.value = nil
                        end
                }),
                TextBox = Roact.createElement("TextBox", {
                        -- ...
                        Text = "",
                        [Roact.Change.Text] = function(rbx)
                                text.value = rbx.Text
                        end
                }),
                Display = Roact.createElement("Frame", {
                        -- ...
                }, {
                        Layout = Roact.createElement("UIListLayout", {
                                -- ...
                        }),
                        Roact.createFragment(list.array)
                })
        })
end

useAsync

promise

</>

Hooks.useAsync(asyncCallback: () → Promise<T>) → HookCreator<UseAsync<T>>

Types

interface UseAsync<T> {

isLoading: boolean

isCancelled: boolean

error: T | nil

result: T | nil

}

Handles async operations and prevents race conditions.

local function fetchData()
        return Promise.new(function()
                return httpRequest("http://url...")
        end)
end

local function HookedComponent(props, hooks)
        local async = useAsync(fetchData)(hooks)

        return Roact.createFragment({
                Loading = async.isLoading and Roact.createElement(...),
                Error = async.error and Roact.createElement(...),
                Result = async.result and Roact.createElement(...)
        })
end

useCounter

</>

Hooks.useCounter(initialValue: number | nil) → HookCreator<UseCounter>

Types

type UseCounter = (

number,

() → void,

() → void,

() → void

)

State hook that tracks a numeric value. If no initial value is passed, it will default to 0.

tip

Counters can be increased/decreased by amount if you pass a number to it's function.

local function HookedComponent(props, hooks)
        local count, increment, decrement, reset = useCounter()(hooks)

        return Roact.createFragment({
                Counter = Roact.createElement(MyCounter, {
                        Text = tostring(count)
                }),
                Inc = Roact.createElement(Button, {
                        OnClick = function()
                                increment()
                        end
                }),
                Dec = Roact.createElement(Button, {
                        OnClick = function()
                                decrement()
                        end
                }),
                Reset = Roact.createElement(Button, {
                        OnClick = function()
                                reset()
                        end
                }),
        })
end

useDebounce

promise

</>

Hooks.useDebounce(

time: number,

callback: () → void,

dependencies: {any}

) → HookCreator<(

() → boolean,

() → void

)>

Hook that delays invoking a function until after wait seconds have elapsed since the last time the debounced function was invoked.

The third argument is the array of values that the debounce depends on, in the same manner as useEffect. The debounce timeout will start when one of the values changes.

tip

You can reach the same result using the hook below.

local function HookedComponent(props, hooks)
        local text, setText = hooks.useState("")
        local debouncedText, setDebouncedText = hooks.useState(text)

        -- Will change debouncedText and render after 1 second of inactivity
        useDebounce(1, function()
                setDebouncedText(text)
        end, { text })(hooks)

        return Roact.createFragment({
                Label = Roact.createElement(Label, {
                        Text = debouncedText
                }),
                Box = Roact.createElement("TextBox", {
                        -- ...,
                        [Roact.Change.Text] = function(rbx)
                                setText(rbx.Text)
                        end
                }),
        })
end

useDebouncedText

promise

</>

Hooks.useDebouncedText(

time: number,

text: string

) → HookCreator<string>

A shortcut for using useDebounce with a string.

local function HookedComponent(props, hooks)
        local text, setText = hooks.useState("")
        local debouncedText = useDebouncedText(1, text)(hooks)

        return Roact.createFragment({
                Label = Roact.createElement(Label, {
                        Text = debouncedText
                }),
                Box = Roact.createElement("TextBox", {
                        -- ...,
                        [Roact.Change.Text] = function(rbx)
                                setText(rbx.Text)
                        end
                }),
        })
end

useDispatch

roact-roduxrodux

</>

Hooks.useDispatch(hooks: RoactHooks) → () → void

Returns a function that executes the dispatch method of the store. You may use it to dispatch actions as needed.

local function Counter(props, hooks)
        local dispatch = useDispatch(hooks)

        return Roact.createFragment({
                Label = Roact.createElement("TextLabel", {
                        Text = props.value
                }),
                Increment = Roact.createElement(Button, {
                        OnClick = function()
                                dispatch({ type = "increment" })
                        end
                })
        })
end

useFlipper

flipper

</>

Hooks.useFlipper(motor: FlipperMotor) → HookCreator<UseFlipper>

Types

type UseFlipper = (

RoactBinding<number>,

FlipperMotor

)

Helper hook that takes a flipper motor, connects it to a binding and returns both.

useForceUpdate

</>

Hooks.useForceUpdate(hooks: RoactHooks) → () → void

Returns a callback that once called, will cause the component to re-render.

useLatest

</>

Hooks.useLatest(value: T) → HookCreator<{value: T}>

Hook that can be used to return the latest state.

tip

This is useful to get access to the latest version of a value, instead of getting the version from the time an asynchronous callback was created, for example.

local function Demo(props, hooks)
        local count, increment = useCounter()(hooks)
        local latestCount = useLatest(count)(hooks)

        useTimeout(5, function()
                print(("Latest count is: %s"):format(latestCount.value))
        end)(hooks)

        return Roact.createFragment({
                Label = Roact.createElement(Label, {
                        Text = tostring(count)
                }),
                Button = Roact.createElement(Button, {
                        OnClick = function()
                                increment()
                        end
                })
        })
end

useMaid

maid

</>

Hooks.useMaid(

maid: Maid,

dependencies: {any}

) → HookCreator<void>

Will clear the maid after one of its dependencies change.

TODO EXAMPLE

usePortal

roact

</>

Hooks.usePortal(options: PortalOptions) → HookCreator<UsePortal>

Types

interface PortalOptions {

Target: Instance

DefaultShow: boolean | nil

DisplayName: string | nil

DisplayOrder: number | nil

IgnoreGuiInset: boolean | nil

OnShow: (() → void) | nil

OnHide: (() → void) | nil

OnClickOutside: ((hide: () → void) → void) | nil

}

interface UsePortal {

Portal: Roact.FunctionComponent

isShow: boolean

show: () → void

hide: () → void

toggle: () → void

}

This helps you render children into an element that exists outside the hierarchy of the parent component.

TODO EXAMPLE

usePrevious

</>

Hooks.usePrevious(state: S) → HookCreator<S>

Simply returns the previous state.

useQueue

</>

Hooks.useQueue(initialValue: {T}) → HookCreator<UseQueue<T>>

Types

interface UseQueue<T> {

add: (element: T) → void

remove: () → void

first: T | nil

last: T | nil

size: number

}

State hook that implements a simple FIFO queue.

useReactiveState

</>

Hooks.useReactiveState(initialState: T) → HookCreator<T>

Types

type HookCreator<T> = (hooks: RoactHooks) → T

Creates a state object that can be changed whenever a new value is assigned to a key.

useRendersSpy

</>

Hooks.useRendersSpy(hooks: RoactHooks) → number

Returns the amount of renders the component has since its mount.

useSelector

roact-roduxrodux

</>

Hooks.useSelector(

selector: (state: S) → R,

equalityFn: ((

a: any,

b: any

) → boolean) | nil

) → HookCreator<R>

Allows you to extract data from the store state, using a selector function.

warning

Selectors should be pure since they are potentially executed multiple times and at arbitrary points in time.

useStore

roact-roduxrodux

</>

Hooks.useStore(hooks: RoactHooks) → Store

Returns a reference to the same store that was passed in to the StoreProvider component.

caution

This should not be used frequently. If you just want to retrieve data from the store, prefer useSelector instead.

useTimeout

promise

</>

Hooks.useTimeout(

time: number,

callback: () → void,

onCancel: ((timeLeft: number) → void) | nil

) → HookCreator<UseTimeout>

Types

interface UseTimeout {

cancel: () → void

reset: () → void

}

Re-renders the component after a specified number of seconds. Provides handles to cancel and/or reset the timeout.

info

This is a one time call. Once the timeout is finished, you cannot use it again. If you are looking into something that can change accordingly to its dependencies, check useDebounce.

local function HookedComponent(props, hooks)
        local text, setText = useState("")
        local timeout = useTimeout(3, function()
                setText("This took 3 seconds!")
        end)(hooks)

        return Roact.createElement("TextLabel", {
                -- ...
                Text = text,
        })
end

useToggle

</>

Hooks.useToggle(initialValue: boolean) → HookCreator<UseToggle>

Types

type UseToggle = (

boolean,

(value: boolean | nil) → void

)

State hook that tracks value of a boolean.

useTween

</>

Hooks.useTween(tweenInfo: TweenInfo) → HookCreator<(

RoactBinding<number>,

UseTween

)>

Types

interface UseTween {

play: () → void

pause: () → void

cancel: () → void

onCompleted: (callback: (playbackState: Enum.PlaybackState) → void) → void

}

Takes a TweenInfo class and returns a binding and an object to manage the tweening.

TODO EXAMPLE

useUndo

</>

Hooks.useUndo(initialPresent: T) → HookCreator<(

UseUndoState<T>,

UseUndo<T>

)>

Types

interface UseUndo<T> {

set: (newPresent: T) → void

reset: (newPresent: T) → void

undo: () → void

redo: () → void

canUndo: boolean

canRedo: boolean

}

interface UseUndoState<T> {

past: {T}

present: T

future: {T}

}

Stores defined amount of previous state values and provides handles to travel through them.

TODO EXAMPLE

useUpdateEffect

</>

Hooks.useUpdateEffect(

callback: () → (() → void) | void,

dependencies: {any} | nil

) → HookCreator<void>

Does the exactly same thing useEffect do, but ignores the first render.