Components

Declarative wrappers around the hooks in /reference/react-hooks. All require a <UnrealBridgeProvider> ancestor.

• <UnrealReadyGate>
  • Props
  • Behavior
  • Example
• <UnrealEvent>
  • Props
  • Behavior
  • Example
• <UnrealValue>
  • Props
  • Behavior
  • Example
• <UnrealDevPanel>
  • Props
  • Behavior
  • Example
• See also

<UnrealReadyGate>

Source: web/sdk/src/components/UnrealReadyGate.tsx

Renders children only after the bridge is ready (UE has fired OnReactReady). Until then, it renders fallback (or nothing).

interface UnrealReadyGateProps {
  fallback?: ReactNode;
  children: ReactNode;
  requireConnected?: boolean;
}

Props

Prop	Type	Default	Notes
fallback	ReactNode	null	Rendered while the gate is closed.
requireConnected	boolean	false	When true, the gate also requires isConnected. Useful if you want to wait on BindUObject separately from OnReactReady.
children	ReactNode	—	Rendered once the gate opens.

Behavior

• Internally reads isReady (and optionally isConnected) from the provider context.
• The gate is a one-way switch in practice: once UE is ready, isReady stays true for the lifetime of the page.

Example

import { UnrealReadyGate } from 'unreal-react-bridge';
import HudRoot from './HudRoot';

export default function App() {
  return (
    <UnrealReadyGate fallback={<div>Loading HUD…</div>}>
      <HudRoot />
    </UnrealReadyGate>
  );
}

<UnrealEvent>

Source: web/sdk/src/components/UnrealEvent.tsx

Headless declarative wrapper around useUnrealEvent. Returns null. Useful when you want to subscribe without adding a hook call in a parent component.

interface UnrealEventProps {
  name: string;
  onMessage: (data: unknown) => void;
}

Props

Prop	Type	Notes
name	string	Event name dispatched by the bridge.
onMessage	(data: unknown) => void	Receives event.detail.

Behavior

• Same lifecycle and ref-based callback semantics as useUnrealEvent.
• Renders null; pure side-effect component.

Example

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

export function Toaster({ push }: { push: (msg: string) => void }) {
  return (
    <UnrealEvent
      name="toast:show"
      onMessage={(d) => push((d as { text: string }).text)}
    />
  );
}

<UnrealValue>

Source: web/sdk/src/components/UnrealValue.tsx

Render-prop binding to useUnrealState. Inherits the same { value: T } auto-unwrap rule.

interface UnrealValueProps<T> {
  source: string;
  initial: T;
  render?: (value: T) => ReactNode;
  children?: (value: T) => ReactNode;
}

Props

Prop	Type	Notes
source	string	Event name to subscribe to.
initial	T	Initial value until the first event arrives.
render	(value: T) => ReactNode	Render function. Takes precedence over children.
children	(value: T) => ReactNode	Render function. Used only when render is not provided.

Behavior

• If neither render nor children is provided, renders null.
• render wins when both are passed.

Example

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

export function Hp() {
  return (
    <UnrealValue<number> source="player:hp" initial={100}>
      {(hp) => <progress value={hp} max={100} />}
    </UnrealValue>
  );
}

<UnrealDevPanel>

Source: web/sdk/src/components/UnrealDevPanel.tsx

Floating diagnostics panel — shows connection state, the initialState dump, a live in/out event log, and a form for manual bridge.send calls. Designed for development; gate it behind a flag in production builds.

interface UnrealDevPanelProps {
  position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
  maxLogEntries?: number;
  defaultExpanded?: boolean;
  eventNameFilter?: (name: string) => boolean;
}

Props

Prop	Type	Default	Notes
position	'top-left' | 'top-right' | 'bottom-left' | 'bottom-right'	'top-right'	Where the panel docks.
maxLogEntries	number	200	Oldest entries are dropped past this size.
defaultExpanded	boolean	false	Whether the panel opens expanded.
eventNameFilter	(name: string) => boolean	name => name.includes(':')	Decides which incoming CustomEvents land in the log. Default matches namespaced events like player:hp.

Behavior

• Incoming events — intercepts window.dispatchEvent while mounted to record every matching CustomEvent. Original behavior is restored on unmount.
• Outgoing events — monkey-patches bridge.send on mount to log calls before forwarding to the original. Restored on unmount.
• Manual trigger — the form invokes bridge.send(name, JSON.parse(payload)). Invalid JSON surfaces under a "Last error" section.
• The panel is position: fixed with zIndex: 9999; it ships with inline styles and has no external CSS dependency.

WARNING

Gate this behind a dev flag. The component monkey-patches window.dispatchEvent and bridge.send — fine for dev, not something you want shipping to production.

{import.meta.env.DEV && <UnrealDevPanel />}

Example

import { UnrealBridgeProvider, UnrealDevPanel } from 'unreal-react-bridge';
import App from './App';

export default function Root() {
  return (
    <UnrealBridgeProvider debug>
      <App />
      {import.meta.env.DEV && <UnrealDevPanel position="bottom-right" defaultExpanded />}
    </UnrealBridgeProvider>
  );
}

See also

• /reference/react-hooks — the hooks these components wrap
• /reference/react-devtools — programmatic event monitoring
• /guide/debugging — debugging workflow