@hiyve/react

React bindings for the Hiyve SDK. Provides a provider component, hooks for connection, room, media, participants, recording, intelligence, presence, and more, plus optional cloud integration for building video conferencing applications with React 18+.

Installation

npx @hiyve/cli login
npm install @hiyve/react @hiyve/core @hiyve/rtc-client
Copy

To use cloud features (AI, room discovery, meeting intelligence), also install:

npm install @hiyve/cloud
Copy

Quick Start

import { HiyveProvider, useConnection, useRoom, useParticipants, useLocalMedia } from '@hiyve/react';

function App() {
  return (
    <HiyveProvider>
      <VideoRoom />
    </HiyveProvider>
  );
}

function VideoRoom() {
  const { joinRoom, isConnecting, error } = useConnection();
  const { room, isInRoom, isOwner } = useRoom();
  const { participants, participantCount } = useParticipants();
  const { isAudioMuted, isVideoMuted, toggleAudio, toggleVideo } = useLocalMedia();

  if (!isInRoom) {
    return (
      <button onClick={() => joinRoom('my-room', 'user-123')} disabled={isConnecting}>
        {isConnecting ? 'Joining...' : 'Join Room'}
      </button>
    );
  }

  return (
    <div>
      <h1>{room?.name} ({participantCount} participants)</h1>
      <button onClick={toggleAudio}>{isAudioMuted ? 'Unmute' : 'Mute'}</button>
      <button onClick={toggleVideo}>{isVideoMuted ? 'Camera On' : 'Camera Off'}</button>
    </div>
  );
}
Copy

Hooks

Each hook tracks only its relevant state, so components re-render only when their data changes.

Connection & Room

Participants & Media

Recording, Streaming & Transcription

Chat & Waiting Room

Intelligence

Layout & Interaction

Stored Rooms, Files & Active Rooms

Join Token

Room Flow

Additional Cameras

Presence & Navigation

Cloud

useUserChat

Manages global chat conversations via the cloud service. Fetches conversation lists, loads message history with cursor-based pagination, sends messages with optimistic updates, and subscribes to real-time message delivery when a conversation is active.

import { useUserChat } from '@hiyve/react';

function ChatView({ userId }: { userId: string }) {
  const {
    conversations,
    activeMessages,
    isLoading,
    isLoadingHistory,
    nextCursor,
    fetchConversations,
    setActiveConversation,
    fetchHistory,
    sendMessage,
    loadMore,
  } = useUserChat();

  useEffect(() => {
    fetchConversations(userId);
  }, [userId, fetchConversations]);

  return (
    <div>
      {conversations.map((c) => (
        <button key={c.roomName} onClick={() => {
          setActiveConversation(c.roomName);
          fetchHistory(c.roomName);
        }}>
          {c.roomName}
        </button>
      ))}
      {activeMessages.map((m) => (
        <p key={m.id}>{m.userId}: {m.content}</p>
      ))}
      {nextCursor && <button onClick={loadMore} disabled={isLoadingHistory}>Load older</button>}
    </div>
  );
}
Copy

useAdditionalCameras

Manages additional camera feeds that join as separate ghost participants. Each camera creates an independent WebRTC connection, so the feed appears automatically in recordings and live streams.

import { useAdditionalCameras } from '@hiyve/react';

function CameraManager() {
  const { cameras, addCamera, removeCamera, removeAll } = useAdditionalCameras({
    roomName: 'my-room',
    ownerUserId: 'user@example.com',
    generateRoomToken: async () => {
      const res = await fetch('/api/generate-room-token', { method: 'POST' });
      const data = await res.json();
      return data.roomToken;
    },
    enabled: true,
  });

  return (
    <div>
      <button onClick={() => addCamera('device-id-123', 'Document Camera')}>Add Camera</button>
      {cameras.map((cam) => (
        <div key={cam.id}>
          {cam.label} - {cam.isActive ? 'Active' : cam.isConnecting ? 'Connecting...' : 'Error'}
          <button onClick={() => removeCamera(cam.id)}>Remove</button>
        </div>
      ))}
    </div>
  );
}
Copy

Options (UseAdditionalCamerasOptions):

Returns (UseAdditionalCamerasReturn):

useRemoteCamera

Manages pairing a remote device (e.g., a phone) as an additional camera feed via QR code. The remote device joins the room as a ghost participant using a time-limited join token.

import { useRemoteCamera } from '@hiyve/react';

function RemoteCameraPairing() {
  const { startPairing, disconnect, qrUrl, status, isExpired } = useRemoteCamera({
    roomName: 'my-room',
    ownerUserId: 'user@example.com',
    enabled: true,
  });

  if (status === 'connected') {
    return <button onClick={disconnect}>Disconnect Phone Camera</button>;
  }

  return (
    <div>
      <button onClick={startPairing}>Pair Phone Camera</button>
      {qrUrl && <img src={`https://api.qrserver.com/v1/create-qr-code/?data=${encodeURIComponent(qrUrl)}`} alt="QR Code" />}
      {isExpired && <p>Link expired. Tap to generate a new one.</p>}
    </div>
  );
}
Copy

Options (UseRemoteCameraOptions):

Returns (UseRemoteCameraReturn):

Ghost Camera Utilities

Utility functions for working with ghost camera participant IDs. Re-exported from @hiyve/core.

Provider Props

HiyveProvider

HiyveProvider is the recommended provider. It accepts all HiyveStoreOptions plus optional cloud configuration:

Cloud Integration

Both room tokens and cloud tokens are generated automatically when your server uses @hiyve/admin middleware. HiyveProvider calls POST /api/generate-room-token and POST /api/generate-cloud-token by default -- no props needed.

// Zero-config -- room and cloud tokens are generated automatically
<HiyveProvider>
  <App />
</HiyveProvider>
Copy

You can still pass custom generators or static tokens to override the defaults:

// Custom token generators (override the defaults)
<HiyveProvider
  generateRoomToken={myCustomRoomTokenGenerator}
  generateCloudToken={myCustomCloudTokenGenerator}
>
  <App />
</HiyveProvider>
Copy

A stable CloudClient instance is available to all child components via useCloudClient():

import { useCloudClient } from '@hiyve/react';

function MyComponent() {
  const cloudClient = useCloudClient();

  if (!cloudClient) return <p>Cloud not configured</p>;

  // Use cloudClient for AI queries, room discovery, etc.
}
Copy

Identity Bridge

When used alongside @hiyve/react-identity, the IdentityProvider automatically provides the authenticated user's email to cloud services and the HiyveProvider. This allows cloud tokens to be generated for the correct user without passing userId manually.

import { useIdentityEmail } from '@hiyve/react';

function Header() {
  const email = useIdentityEmail();
  return email ? <span>Signed in as {email}</span> : null;
}
Copy

Advanced: Direct Store Access

For custom integrations, access the HiyveStore directly:

import { useStore } from '@hiyve/react';

function CustomComponent() {
  const store = useStore();
  // Access store methods for custom integrations
}
Copy

Re-exported Types

All core state types are re-exported from @hiyve/core for convenience. The full set of types available from @hiyve/react:

Store

Connection & Room

Participants & Media

Capture (Recording, Streaming, Transcription)

Chat & Waiting Room

Audio Processing & Layout

Intelligence

Files & Stored Rooms

Active Rooms (Cloud)

Client

Join Tokens

Hook-Specific Types

Cloud

import type {
  HiyveStoreState,
  Participant,
  RoomInfo,
  ChatMessage,
  TranscriptionEntry,
  RecordingState,
  StreamingState,
  WaitingRoomUser,
} from '@hiyve/react';
Copy

Contexts

For advanced integrations, the underlying React contexts are exported:

Constants

Join token error codes, re-exported from @hiyve/core:

Utilities

Requirements

• React 18+
• @hiyve/core and @hiyve/rtc-client as peer dependencies
• @hiyve/cloud as optional peer dependency (for cloud features)

Related Packages

• @hiyve/core -- Framework-agnostic state store (works with React, Angular, Vue, or any framework)
• @hiyve/react-ui -- Pre-built UI components (video tile, video grid, control bar, sidebar)
• @hiyve/react-capture -- Recording, streaming, and transcription components
• @hiyve/react-collaboration -- Chat, polls, Q&A, and file manager components
• @hiyve/react-intelligence -- AI assistant, meeting summary, alerts, and sentiment
• @hiyve/react-notes -- Collaborative meeting notes
• @hiyve/react-whiteboard -- Collaborative whiteboard

License

Proprietary - Hiyve SDK