@chris-pma/ui

React hooks and utilities for building FiveM NUI interfaces with TypeScript.

Installation

npm install @chris-pma/ui

or with pnpm:

pnpm add @chris-pma/ui

or with yarn:

yarn add @chris-pma/ui

Features

• 🎣 React Hooks for FiveM NUI communication
• 🔄 Type-safe data fetching with TypeScript
• 🧪 Development-friendly with mock data support
• 🎯 Simple API for common NUI patterns

API

fetchNui

A type-safe wrapper around the Fetch API designed for CEF/NUI communication with FiveM resources.

async function fetchNui<T = any>(
	resourceName: string,
	eventName: string,
	data?: any,
	mockData?: T
): Promise<T>;

Parameters:

• resourceName - The name of your FiveM resource
• eventName - The endpoint event name to target
• data - Data to send in the NUI callback
• mockData - Mock data returned when running in browser (for development)

Example:

import { fetchNui } from "@chris-pma/ui";

// Fetch player data from your resource
const playerData = await fetchNui<{ name: string; id: number }>(
	"my-resource",
	"getPlayerData",
	{ requestId: 123 },
	{ name: "John Doe", id: 1 } // Mock data for browser testing
);

useNuiEvent

A React hook for listening to messages sent from the client scripts to the NUI.

function useNuiEvent<T = any>(action: string, handler: (data: T) => void): void;

Parameters:

• action - The specific action to listen for
• handler - Callback function invoked when the action is received

Example:

import { useNuiEvent } from "@chris-pma/ui";
import { useState } from "react";

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

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

	return visible ? <div>Hello World</div> : null;
}

useDebug

A development utility hook that dispatches mock NUI events for testing your interface in a browser.

function useDebug<P>(events: DebugEvent<P>[], timer?: number): void;

Parameters:

• events - Array of debug events to dispatch
• timer - Delay in milliseconds before dispatching events (default: 1000)

Example:

import { useDebug } from "@chris-pma/ui";
import { useEffect } from "react";

function App() {
	useDebug(
		[
			{
				app: "my-resource",
				action: "setVisible",
				data: { visibility: true },
			},
			{
				app: "my-resource",
				action: "updateData",
				data: { value: 42 },
			},
		],
		2000
	);

	// Your component logic...
}

Usage Example

Here's a complete example of a FiveM NUI interface:

import React, { useState } from "react";
import { useNuiEvent, fetchNui, useDebug } from "@chris-pma/ui";

function App() {
	const [visible, setVisible] = useState(false);
	const [data, setData] = useState<string>("");

	// Debug events for browser testing
	useDebug([{ app: "my-resource", action: "show", data: { message: "Hello!" } }]);

	// Listen for visibility changes
	useNuiEvent<{ message: string }>("show", (data) => {
		setVisible(true);
		setData(data.message);
	});

	const handleSubmit = async () => {
		try {
			await fetchNui("my-resource", "submitData", { message: data });
			setVisible(false);
		} catch (error) {
			console.error("Failed to submit data:", error);
		}
	};

	if (!visible) return null;

	return (
		<div>
			<p>{data}</p>
			<button onClick={handleSubmit}>Submit</button>
		</div>
	);
}

export default App;

TypeScript Support

This package is written in TypeScript and provides full type definitions. All hooks and utilities support generic types for type-safe development.

Browser Detection

The fetchNui function automatically detects whether it's running in a browser or in-game environment. When running in a browser, it will return the provided mock data instead of making a fetch request.

Repository

Visit the GitHub repository for more information, examples, and to report issues.

License

MIT