@elvenvtt/client-react

React hooks for Elven — build companion apps that connect to Elven sessions.

A companion app is a sandboxed iframe app rendered alongside an Elven session. It can read live game state (actors, combat, dice, chat), send commands, register rail tabs, and react to events. This package wraps the @elvenvtt/client connection layer in idiomatic React hooks.

Apps built with this package work both inside Elven (via the postMessage bridge) and standalone (via direct WebSocket to sync.elvenvtt.com). The provider auto-detects which mode you're in.

Install

npm install @elvenvtt/client-react @elvenvtt/client react react-dom

Quick example

import { createRoot } from 'react-dom/client';
import {
  ElvenProvider,
  useActors,
  useChat,
  useDice
} from '@elvenvtt/client-react';

function App() {
  const actors = useActors();
  const { send } = useChat();
  const { roll } = useDice();

  return (
    <div>
      <h1>{actors.length} actors in this session</h1>
      <ul>{actors.map(a => <li key={a.id}>{a.name}</li>)}</ul>
      <button onClick={() => send('Hello from my companion!')}>Say hi</button>
      <button onClick={() => roll('1d20')}>Roll d20</button>
    </div>
  );
}

createRoot(document.getElementById('root')).render(
  <ElvenProvider>
    <App />
  </ElvenProvider>
);

In bridge mode (loaded inside Elven), ElvenProvider finds the parent shell automatically. In standalone mode (running in its own tab or a phone), pass session and name props:

<ElvenProvider session={inviteCode} name="Player">
  <App />
</ElvenProvider>

Hooks

Connection

| Hook | Purpose | |---|---| | useElven() | Access the underlying client + session metadata | | useConnection() | { status, error } — connecting / connected / disconnected | | useBridgeMode() | true if running inside Elven (vs standalone) | | useIsHost() | true if the local user is the session host |

Actors

| Hook | Purpose | |---|---| | useActors() | Reactive array of all actors in the session | | useActor(id) | Reactive single actor lookup | | useMyActor() | The actor bound to the current player; provides bind / unbind | | useActorActions() | Imperative actions: move, update, spawn, delete | | useSelection() | Currently-selected actor ids |

Combat & dice

| Hook | Purpose | |---|---| | useCombat() | Live combat state — turn, round, initiative | | useDice() | Roll dice; results sync via the dice box |

Chat & events

| Hook | Purpose | |---|---| | useChat() | Send chat messages | | useEvent(event, handler) | Subscribe to ephemeral session events | | useEmit() | Send custom ephemeral events to the session | | usePresence() | Connected players + their cursors / active state | | useNotify() | Show toasts to a specific actor | | usePing() | Send a ping to the table |

Game state

| Hook | Purpose | |---|---| | useVars() | Reactive game variables (campaign-scoped key/value store) | | useMap() | Active map / scene info | | useToast() | Local UI toast (companion-side only) |

Effects

| Hook | Purpose | |---|---| | useVFX() | Trigger visual effects (particle bursts) | | useVoice() | WebRTC voice chat | | useVideo() | WebRTC video chat | | useScreenShare() | Screen sharing | | <VoiceAudio /> | Audio playback component |

Companion app layout (in-Elven only)

| Hook | Purpose | |---|---| | useZone() | Zone-specific state (right / top / bottom companion zones) | | useWidget() | Floating widget state | | useWidgetDrag() | Drag-to-place widget interactions | | useRailTab() | Active rail tab + navigation |

Cloud (advanced)

| Hook | Purpose | |---|---| | useCloud() | Cloudflare Worker-side state for persistent companions | | useSharedCloud() | Shared cloud state across multiple sessions | | useInstanceId() | Unique id for this companion instance |

Bridge mode vs standalone mode

ElvenProvider detects automatically:

• Bridge mode (no session prop, running in iframe under Elven) → uses postMessage to the parent. State is whatever the host session has.
• Standalone mode (session prop provided) → opens a WebSocket to wss://sync.elvenvtt.com and joins the session directly. Same hooks, same API.

This means a single companion app source can ship as both an in-Elven panel AND a standalone phone/tablet client.

Companion app shape

A companion app exports a companionDef:

export const companionDef = {
  id: 'my-app',
  name: 'My App',
  version: '1.0.0',
  mount(container, { session, name }) {
    const root = createRoot(container);
    root.render(
      <ElvenProvider session={session} name={name}>
        <App />
      </ElvenProvider>
    );
    return () => root.unmount();
  }
};

The platform calls mount when loading the companion. It returns a cleanup function called on unmount.

TypeScript

Full types ship with the package. All hooks are typed; reactive types come from @elvenvtt/client. Re-exported types include Actor, CombatState, PresenceInfo, MapInfo, MapListEntry, VoicePeer, VoiceState.

Where to learn more

• Creator docs — full guide to building Elven companions
• @elvenvtt/client — vanilla JS client this wraps
• Hello Companion starter — minimum viable example to fork
• 5e Companion (reference implementation) — full game system as worked example

License

MIT