Hooks

All hooks require a <UnrealBridgeProvider> ancestor. They throw if used outside one.

• useUnrealBridge
  • Returns
  • Behavior
  • Example
• useUnrealEvent
  • Params
  • Returns
  • Behavior
  • Example
• useUnrealState
  • Params
  • Returns
  • Auto-unwrap rule
  • Example
• useInitialState
  • Params
  • Returns
  • Behavior
  • Example
• See also

useUnrealBridge

Source: web/sdk/src/hooks/useUnrealBridge.ts

Returns the imperative send API plus live connection flags.

function useUnrealBridge(): {
  send: (eventName: string, data?: unknown) => void;
  isConnected: boolean;
  isReady: boolean;
};

Returns

Field	Type	Notes
send	(eventName, data?) => void	Invokes window.ue.bridge.onreactevent(eventName, JSON.stringify(data)). Stable across renders (wrapped in useCallback). If data is already a string, it is forwarded verbatim instead of re-serialized.
isConnected	boolean	true once window.ue.bridge exists (UE completed BindUObject).
isReady	boolean	true once UE fired OnReactReady (lifecycle step 5).

Behavior

• When the bridge is not connected, send logs a console.warn and returns. The web side does not buffer or queue outgoing events; any queueing policy is owned by the native bridge.
• send does not return a promise. Delivery is fire-and-forget; use a UE-side callback event if you need acknowledgement.

Example

import { useUnrealBridge } from 'unreal-react-bridge';

export function CastButton() {
  const { send, isReady } = useUnrealBridge();
  return (
    <button disabled={!isReady} onClick={() => send('skill:cast', { id: 'fireball' })}>
      Cast
    </button>
  );
}

useUnrealEvent

Source: web/sdk/src/hooks/useUnrealEvent.ts

Subscribes to a CustomEvent dispatched by the bridge.

function useUnrealEvent<T = unknown>(
  eventName: string,
  callback: (data: T) => void,
): void;

Params

Param	Type	Notes
eventName	string	The event name UE used in Push… / Broadcast….
callback	(data: T) => void	Invoked with event.detail (already parsed to a JS object).

Returns

Nothing. Cleanup is automatic on unmount or when eventName changes.

Behavior

• The latest callback is held in a ref and re-read on every dispatch, so you don't need useCallback to keep stale closures out — but you also don't pay a resubscribe cost when the callback identity changes.
• The subscription itself is keyed on bridge and eventName, so changing the name will tear down the old listener and attach a new one.
• The hook reads event.detail, never the raw Event. If UE dispatches a non-CustomEvent, data is the Event object itself (see BridgeManager.on).

Example

import { useState } from 'react';
import { useUnrealEvent } from 'unreal-react-bridge';

export function HpReadout() {
  const [hp, setHp] = useState(100);
  useUnrealEvent<{ value: number }>('player:hp', (d) => setHp(d.value));
  return <span>HP: {hp}</span>;
}

TIP

If your event always carries { value: T } (the typed-payload envelope from PushFloat / PushInt / PushString / PushBool / PushVector / PushStruct), prefer useUnrealState — it auto-unwraps for you.

useUnrealState

Source: web/sdk/src/hooks/useUnrealState.ts

Subscribes to an event and exposes its latest payload as React state.

function useUnrealState<T>(eventName: string, initialValue: T): T;

Params

Param	Type	Notes
eventName	string	Event to track.
initialValue	T	Used until the first dispatch.

Returns

T — the most recent payload (or initialValue before any dispatch).

Auto-unwrap rule

If the incoming payload is an object with exactly one own key named value, the hook returns the value of value directly. Otherwise the full payload is returned untouched.

Source (UE)	Payload over the wire	useUnrealState<T> returns
PushFloat("player:hp", 75)	{ value: 75 }	75
PushString("player:name", "Sigrid")	{ value: "Sigrid" }	"Sigrid"
PushMap("hud", { value: 5, max: 10 })	{ value: 5, max: 10 }	{ value: 5, max: 10 }
PushRaw("inv", { items: [...] })	{ items: [...] }	{ items: [...] }

The single-key check is deliberate: any object with siblings (e.g. { value, max }) is passed through as-is so legitimate domain fields aren't dropped.

Example

import { useUnrealState } from 'unreal-react-bridge';

export function HpBar() {
  const hp = useUnrealState<number>('player:hp', 100);
  return <progress value={hp} max={100} />;
}

For multi-field payloads, type the generic accordingly:

type HudState = { value: number; max: number };
const hud = useUnrealState<HudState>('hud:mp', { value: 0, max: 0 });

useInitialState

Source: web/sdk/src/hooks/useInitialState.ts

Reads a slice of the host UE app's initial state, delivered on the ue5-bridge-ready event.

function useInitialState<T>(key: string): T | undefined;

Params

Param	Type	Notes
key	string	Top-level key inside detail.initialState.

Returns

T | undefined — the value at initialState[key], or undefined if the key is absent or the bridge hasn't fired its ready event yet.

Behavior

• The snapshot is captured once when ue5-bridge-ready fires, stored in provider state, and stays stable across renders thereafter.
• This is not a live subscription: subsequent Push… events do not mutate initialState. Use useUnrealState for streaming updates.
• If you need the entire snapshot object, read it via the context directly (advanced) or call this hook for each known top-level key.

Example

import { useInitialState } from 'unreal-react-bridge';

type Player = { name: string; level: number };

export function PlayerCard() {
  const player = useInitialState<Player>('player');
  if (!player) return null;
  return <div>{player.name} · Lv {player.level}</div>;
}

See /guide/initial-state for the full lifecycle.

See also

• /reference/react-components — declarative wrappers (UnrealEvent, UnrealValue, UnrealReadyGate)
• /reference/bp-subsystem — Blueprint side that emits these events
• /guide/lifecycle — connect / ready handshake