fivem-nui-react

React hooks and utilities for FiveM NUI development.

Installation

npm install fivem-nui-react

Features

• useNuiEvent - Listen for NUI messages from Lua
• fetchNui - Send requests to Lua client and receive responses
• useNuiCallback - Hook for NUI requests with loading/error states and callback
• useSendNui - Hook for sending data without expecting a response
• isEnvBrowser - Check if running in browser (debug mode)
• Mock data support - Test your UI in browser with simulated responses

API Reference

useNuiEvent

Listen for NUI messages sent from Lua.

useNuiEvent<T>(action: string, handler: (data: T) => void, options?: UseNuiEventOptions<T>): void

Parameters:

• action - The action name to listen for
• handler - Callback function executed when message is received
• options - Optional mock data configuration for browser testing

Example:

import { useNuiEvent } from "fivem-nui-react";

function App() {
  const [visible, setVisible] = useState(false);

  useNuiEvent<{ show: boolean }>("toggleUI", (data) => {
    setVisible(data.show);
  });

  // With mock data for browser testing
  useNuiEvent<{ show: boolean }>("toggleUI", (data) => setVisible(data.show), {
    mockData: { show: true },
    mockDelay: 1000,
  });

  return visible ? <div>UI Content</div> : null;
}

Fivem client side:

SendNUIMessage({
  action = "toggleUI",
  data = { show = true }
})

fetchNui

Send a request to the Fivem client and receive a response.

fetchNui<T, D>(eventName: string, data?: D, options?: FetchNuiOptions<T>): Promise<T>

Parameters:

• eventName - The NUI callback event name
• data - Data to send to Lua
• options - Optional mock data configuration for browser testing

Example:

import { fetchNui } from "fivem-nui-react";

interface PlayerData {
  name: string;
  level: number;
}

async function getPlayer() {
  const player = await fetchNui<PlayerData>("getPlayerData", { id: 1 });
  console.log(player.name, player.level);
}

// With mock data for browser testing
async function getPlayerMocked() {
  const player = await fetchNui<PlayerData>(
    "getPlayerData",
    { id: 1 },
    {
      mockData: { name: "John", level: 10 },
      mockDelay: 500,
    },
  );
  console.log(player.name, player.level);
}

Lua side:

RegisterNUICallback("getPlayerData", function(data, cb)
  local playerId = data.id
  -- Fetch player data...
  cb({ name = "John", level = 10 })
end)

useNuiCallback

A hook that wraps fetchNui with loading and error state management.

useNuiCallback<T, D>(
  eventName: string,
  callback: (data: T) => void,
  options?: UseNuiCallbackOptions<T>
): [fetchFn: (data?: D) => Promise<T>, state: { loading: boolean, error: Error | null }]

Parameters:

• eventName - The NUI callback event name
• callback - Callback function executed when response is received
• options - Optional mock data configuration for browser testing

Returns:

• fetchFn - Function to trigger the request
• state.loading - Boolean indicating if request is in progress
• state.error - Error object if request failed

Example:

import { useNuiCallback } from "fivem-nui-react";

interface PlayerData {
  name: string;
  level: number;
}

function PlayerInfo() {
  const [player, setPlayer] = useState<PlayerData | null>(null);

  const [fetchPlayer, { loading, error }] = useNuiCallback<PlayerData>(
    "getPlayerData",
    (data) => setPlayer(data),
    {
      mockData: { name: "John", level: 10 },
      mockDelay: 500,
    },
  );

  useEffect(() => {
    fetchPlayer({ id: 1 });
  }, [fetchPlayer]);

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
  if (!player) return null;

  return (
    <div>
      <p>Name: {player.name}</p>
      <p>Level: {player.level}</p>
    </div>
  );
}

useSendNui

A hook for sending data to the Lua client without expecting a response.

useSendNui<D>(
  eventName: string,
  options?: UseSendNuiOptions
): [sendFn: (data?: D) => Promise<void>, state: { loading: boolean, error: Error | null }]

Parameters:

• eventName - The NUI callback event name
• options - Optional mock delay configuration for browser testing

Returns:

• sendFn - Function to send data
• state.loading - Boolean indicating if request is in progress
• state.error - Error object if request failed

Example:

import { useSendNui } from "fivem-nui-react";

function CloseButton() {
  const [closeUI, { loading }] = useSendNui<{ reason: string }>("closeUI");

  const handleClose = () => {
    closeUI({ reason: "user_clicked" });
  };

  return (
    <button onClick={handleClose} disabled={loading}>
      {loading ? "Closing..." : "Close"}
    </button>
  );
}

Lua side:

RegisterNUICallback("closeUI", function(data, cb)
  SetNuiFocus(false, false)
  cb("ok")
end)

isEnvBrowser

Check if running in browser (outside FiveM).

isEnvBrowser(): boolean

Example:

import { isEnvBrowser } from "fivem-nui-react";

if (isEnvBrowser()) {
  console.log("Running in browser - debug mode");
} else {
  console.log("Running in FiveM");
}

Browser Testing (Mock Data)

All hooks and functions support mock data for testing your UI in a regular browser without FiveM.

When isEnvBrowser() returns true:

• useNuiEvent will trigger the handler with mockData after mockDelay milliseconds
• fetchNui will return mockData after mockDelay milliseconds
• useNuiCallback will call the callback with mockData after mockDelay milliseconds
• useSendNui will simulate a delay with mockDelay milliseconds

Options:

• mockData - The data to return in browser mode
• mockDelay - Delay in milliseconds before returning data (default: 500ms)

TypeScript Support

All functions are fully typed with generics:

// Define your types
interface ShowUIData {
  visible: boolean;
  title: string;
}

interface PlayerRequest {
  id: number;
}

interface PlayerResponse {
  name: string;
  level: number;
}

// Use with type parameters
useNuiEvent<ShowUIData>("showUI", (data) => {
  // data is typed as ShowUIData
  console.log(data.visible, data.title);
});

const player = await fetchNui<PlayerResponse, PlayerRequest>("getPlayer", {
  id: 1,
});
// player is typed as PlayerResponse

const [fetchPlayer, { loading }] = useNuiCallback<
  PlayerResponse,
  PlayerRequest
>("getPlayer", (data) => console.log(data.name));

License

MIT