useNuiMutation

Overview

The useNuiMutation hook provides an easy and effective way to send mutations (i.e., actions that modify data or trigger side effects) to the FiveM client in a React-based environment. It simplifies the process of interacting with the NUI (Native UI) system by sending requests and handling responses with custom callbacks.

Use useNuiMutation for sending data (e.g., handle click), as it's designed for mutations, while useNuiQuery is for fetching data.

Usage

Importing the Hook

import { useNuiMutation } from "@yankes/fivem-react/hooks";

Parameters

useNuiMutation does not require any parameters for initialization. However, when invoking the mutate function, you have to pass the following parameters:

Parameter	Type	Description	Optional
endpoint	string	Endpoint where you send NUI Callback.
options	Options	Additional options

Options

Object contains parameters below (all parameters are optional):

Parameter	Type	Description
body	string | number | boolean | Array<unknown> | Record<string, unknown>	The body parameter contains the data sent with the NUI request, supporting various types without requiring manual string conversion.
onSuccess	(value: Response | void) ⇒ void | PromiseLike<void>	The onSuccess callback is triggered on a successful NUI response, receiving the data for further processing.
onError	(reason: unknown) ⇒ void | PromiseLike<void> | null | undefinded	The onError callback is triggered if the NUI request fails, allowing error handling or recovery actions.
onFinally	() ⇒ void | null | undefinded	The onFinally callback runs after the NUI request completes, regardless of success or failure, for cleanup or final actions.

Return Value

The hook returns an object with the following properties:

Name	Type	Description
mutate	(endpoint: string, options?: Options) ⇒ void	A function that accepts an endpoint string and an optional options object. The mutate function sends the NUI mutation request.
isPending	boolean	A boolean state indicating whether the mutation is currently in progress. It can be used to show loading indicators or disable UI elements while the mutation is pending.

Example

ReactJS

import { useState } from "react";
import { useNuiMutation } from "@yankes/fivem-react/hooks";

export const MyComponent = () => {
    const [message, setMessage] = useState("");
    const { mutate, isPending } = useNuiMutation();

    const handleSubmit = async () => {
        mutate("/send-message", {
            body: { message },
            onSuccess: (response) => {
                console.log("Message sent successfully", response);
                setMessage("");
            },
            onError: (error) => {
                alert("Failed to send message");
            },
            onFinally: () => {
                console.log("Mutation process complete");
            }
        });
    };

    return (
        <div>
            <input
                type="text"
                value={message}
                onChange={(e) => setMessage(e.target.value)}
                disabled={isPending}
            />
            <button onClick={handleSubmit} disabled={isPending}>
                {isPending ? "Sending..." : "Send Message"}
            </button>
        </div>
    );
};

LUA

RegisterNUICallback("send-message", function(data, cb)
    if data.message then
        ExecuteCommand(data.message)
        cb(true)
    else
        cb(false)
    end
end)

How It Works

1. The useNuiMutation hook initializes a mutate function and a isPending state.

2. When the mutate function is called, it receives an endpoint and an optional options object containing data and callbacks.

3. The mutate function uses startTransition to manage the mutation process, ensuring the UI remains responsive.

4. The fetchNui function sends the NUI request to the FiveM client with the specified endpoint and body data.

5. If the request is successful, the onSuccess callback is triggered, allowing the response to be processed.

6. If an error occurs during the mutation, the onError callback is executed to handle the error.

7. After the mutation process completes, regardless of success or failure, the onFinally callback is called for cleanup operations.

8. The isPending state is updated based on whether the mutation is still in progress, allowing the UI to reflect the current request status (e.g., showing loading indicators or disabling UI elements).

Notes

• The hook provides flexible callbacks (onSuccess, onError, and onFinally) for handling the response lifecycle in a structured manner.

• The mutation request lifecycle is managed automatically, eliminating the need for manual cleanup.

• The isPending state helps track the request status, enabling dynamic UI behavior, such as displaying loading spinners or disabling buttons while the request is in progress.

• The hook abstracts away the complexity of dealing with NUI requests, allowing you to focus on handling the response and UI interactions.

Conclusion

The useNuiMutation hook provides a straightforward and flexible way to handle mutations within a React-based FiveM environment. It abstracts away the complexity of managing NUI requests, keeping your code clean, responsive, and easy to maintain.