README.md

react-roblox-hooks

This package is a collection of hooks for react-lua, specifically target for development on Roblox.

Installation

Add react-roblox-hooks in your dependencies:

yarn add @seaofvoices/react-roblox-hooks

Or if you are using npm:

npm install @seaofvoices/react-roblox-hooks

Content

Hooks:

• useService
• useCamera
• useCameraCFrame
• useEvent
• useGuiObjectSizeBinding
• useLocalPlayer
• useObjectLocation
• usePropertyChange
• useTaggedInstances
• useTextSize
• useViewportSize

Components:

• ServiceProvider

useService

function useService(className: string): Instance

A hook that returns the given service from its class name, as usually done with game:GetService(className). Usefull when testing a component that requires a mock of a given service, which can be provided using the ServiceProvider

Example

local function Component(props)
    local camera = useCamera() -- get the Camera object

    -- ...
end

useCamera

function useCamera(): Camera

A hook that returns the CurrentCamera value from the Workspace.

Example

local function Component(props)
    local camera = useCamera() -- get the Camera object

    -- ...
end

useCameraCFrame

function useCameraCFrame(fn: (CFrame) -> (), deps: { any })

A hook to subscribe to each camera CFrame changes.

Changes in the dependency array will disconnect and reconnect with the updated function.

Example

local function Component(props)
    local visible, setVisible = useState(false)

    useCameraCFrame(function(cframe: CFrame)
        local distance = ... -- compute distance from player

        -- trigger a state update to make something visible
        -- when the camera is close enough
        setVisible(distance < 30)
    end, {})

    -- ...
end

useEvent

A hook to subscribe to Roblox events. Runs a function when the specified event is triggered.

Changes in the dependency array will disconnect and reconnect with the updated function.

function useEvent<T...>(
    event: RBXScriptSignal<T...>,
    fn: (T...) -> (),
    deps: { any }
)

Example

local function Component(props)

    -- ...
end

useGuiSizeBinding

A hook that returns a binding for a GuiObject's AbsoluteSize (a Vector2). Returns a ref that has to be assigned to a GuiBase2d instance.

function useGuiSizeBinding(): (React.Ref<GuiBase2d>, React.Binding<Vector2>)

Example

local function Component(props)
    local ref, binding = useGuiSizeBinding()

    return React.createElement("Frame", {
        -- assign the ref to the frame and the binding will
        -- automatically update with the frame AbsoluteSize property
        ref = ref,
    })
end

useLocalPlayer

A hook that returns the LocalPlayer object. Use this hook to access information and perform actions related to the local player. Note that this hook will only work when used on client-side context scripts.

function useLocalPlayer(): Player

Example

local function Component(props)
    local player = useLocalPlayer(): Player
    -- ...
end

useObjectLocation

A hook to track the location (CFrame) changes of a given PVInstance (typically a model or BasePart). It enables a component to respond to object movements in a game.

function useObjectLocation(
    object: PVInstance?,
    fn: (CFrame) -> (),
    deps: { any }
)

Example

local function Component(props)

    -- ...
end

usePropertyChange

A hook to subscribe to property changes of a given Instance. Errors if the property does not exist on the Instance. If the given instance if nil is simply disconnects the previous connection.

function usePropertyChange<T>(
    instance: Instance?,
    property: string,
    fn: (T) -> (),
    deps: { any }
)

Example

local function Component(props)

    -- ...
end

useTaggedInstances

A hook to retrieve instances in the game with a specified CollectionService tag. It returns an array of instances (or a mapped array based on a mapping function).

function useTaggedInstances(tagName: string): { Instance }
function useTaggedInstances(tagName: string, mapFn: (Instance) -> T?): { T }

Example

local function Component(props)

    -- ...
end

useTextSize

A hook to calculate the size of a given text string based on provided options such as font size and style. It is useful for dynamically adjusting UI elements based on the size of the displayed text.

function useTextSize(text: string, options: Options): Vector2
-- where
type Options = { size: number, font: Font, width: number? }

Example

local function Component(props)

    -- ...
end

useViewportSize

A hook to subscribe to changes in the viewport size. It enables components to respond to screen size changes, allowing for responsive adjustments.

function useViewportSize(fn: (Vector2) -> (), deps: { any })

Example

local function Component(props)

    -- ...
end

ServiceProvider

A component that can override the default service provider (which simply calls game:GetService(className)) with a custom implementation

Example

local function MockServiceProvider(props)
    local mocks = props.mocks
    local function provideMocks(className: string): Instance
        -- return the mocked service or default to the real one
        return mocks[className] or game:GetService(className)
    end

    return React.createElement(ServiceProvider, {
        value = provideMocks
    })
end

License

This project is available under the MIT license. See LICENSE.txt for details.