@hiyve/react-ui

UI components for Hiyve video conferencing -- video grid, video tiles, control bar, device selector, audio monitor, participant list, sidebar, waiting room, and join token.

Installation

npx @hiyve/cli login
npm install @hiyve/react-ui
Copy

Peer Dependencies

npm install react react-dom @mui/material @mui/icons-material @emotion/react @emotion/styled @hiyve/react @hiyve/rtc-client @hiyve/utilities
Copy

Quick Start

import { HiyveProvider, useConnection, useRoom } from '@hiyve/react';
import { VideoGrid, ControlBar } from '@hiyve/react-ui';

function App() {
  const generateToken = async () => {
    const res = await fetch('/api/room-token', { method: 'POST' });
    const { roomToken } = await res.json();
    return roomToken;
  };

  return (
    <HiyveProvider generateRoomToken={generateToken}>
      <VideoRoom />
    </HiyveProvider>
  );
}

function VideoRoom() {
  const { joinRoom } = useConnection();
  const { isInRoom } = useRoom();

  if (!isInRoom) {
    return <button onClick={() => joinRoom('my-room', 'user-123')}>Join</button>;
  }

  return (
    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
      <VideoGrid
        localVideoElementId="local-video"
        localUserName="Me"
        layout="grid"
        style={{ flex: 1 }}
      />
      <ControlBar
        showAudioToggle
        showVideoToggle
        showOutputToggle
        showScreenShare
        showSettings
        showLeaveButton
        onLeave={() => console.log('Left room')}
      />
    </div>
  );
}
Copy

Components

Video

Pre-built layout handlers for VideoGrid (pass via customLayoutHandler):

Control Bar

Device Selection

Audio

Participants

Sidebar

Portal Layout

Waiting Room

Connecting Screen

Join Form

Join Token

General Purpose

Hooks

useMuiThemedColors

Returns themed color bundles derived from the active MUI theme — one bundle per Hiyve editor (notes, whiteboard, assignments, clips, chat, polls, Q&A, alerts, sentiment, intelligence hub, participant list). Bundles update automatically when the user toggles light/dark mode or changes the theme's accent color.

The hook reads app-provided surface tokens from theme.palette.mupiCustom.* when present, otherwise derives sensible defaults from standard MUI tokens (background.paper, background.default, divider, etc.).

import { useMuiThemedColors } from '@hiyve/react-ui';
import { NoteEditor } from '@hiyve/react-notes';
import { Whiteboard } from '@hiyve/react-whiteboard';
import { ChatPanel } from '@hiyve/react-collaboration';

function MeetingTools() {
  const colors = useMuiThemedColors();
  return (
    <>
      <NoteEditor colors={colors.noteColors} />
      <Whiteboard colors={colors.whiteboardColors} />
      <ChatPanel colors={colors.chatColors} />
    </>
  );
}
Copy

useAutoHide

Manages auto-hide behavior based on user activity. After a configurable timeout of inactivity (mouse, touch, keyboard), the hook returns styles that animate the target element out of view. Supports nested pause/resume for menus and dropdowns.

import { useAutoHide } from '@hiyve/react-ui';
import type { UseAutoHideOptions } from '@hiyve/react-ui';

function MyToolbar() {
  const { isVisible, wrapperStyle, contentStyle, pauseAutoHide, resumeAutoHide } = useAutoHide({
    timeout: 3000,
    animationDuration: 300,
    animationEasing: 'ease-in-out',
    onVisibilityChange: (visible) => console.log('Toolbar visible:', visible),
  });

  return (
    <div style={wrapperStyle}>
      <div style={contentStyle}>
        <button
          onMouseEnter={pauseAutoHide}
          onMouseLeave={resumeAutoHide}
        >
          Menu
        </button>
      </div>
    </div>
  );
}
Copy

Usage Examples

Speaker Layout for Presentations

<VideoGrid
  localVideoElementId="local-video"
  localUserName="Me"
  layout="speaker"
  styles={{ filmstripHeight: 150 }}
/>
Copy

Recording and Intelligence Features (Owner Only)

<ControlBar
  showRecordingMenu
  showLayoutSelector
  showHandRaise
  onRecordingStarted={(options) => console.log('Recording started', options)}
  onRecordingStopped={() => console.log('Recording stopped')}
  onIntelligenceModeStarted={(config) => console.log('Intelligence started', config)}
  onIntelligenceModeStopped={() => console.log('Intelligence stopped')}
  onLeave={handleLeave}
/>
Copy

To surface recording/streaming status in your own chrome instead of the built-in spots, hide both indicators and read the state from useRecording() / useStreaming():

// Hide the inline duration + active badges beside the recording button
<ControlBar showRecordingMenu showRecordingStatus={false} onLeave={handleLeave} />

// Hide the "REC"/"LIVE" badge on the local video tile
<VideoGrid localVideoElementId="local-video" showRecordingIndicator={false} />
Copy

Compact Control Bar (Small Screens)

Set variant="compact" for mobile or narrow layouts. The primary controls (audio toggle, video toggle, hand raise, leave, and sidebar toggle) stay inline, and every other enabled control (device settings, screen share, recording menu, layout selector, output toggle, camera menu, and renderExtraControls output) collapses into a single "More" button that opens a popover. Each control is still gated by its own show* prop; the More button only appears when at least one overflow control is enabled. Compact mode uses tighter spacing and adds bottom padding that accounts for device safe areas (e.g. phone home indicators).

<ControlBar
  variant="compact"
  showRecordingMenu
  onSidebarToggle={toggleSidebar}
  onLeave={handleLeave}
/>
Copy

Compact spacing is configurable via the styles prop (compactGap and compactPadding, both 8 by default):

<ControlBar variant="compact" styles={{ compactGap: 12, compactPadding: 12 }} />
Copy

Pre-Join Device Preview

import { DevicePreview } from '@hiyve/react-ui';
import type { SelectedDevices } from '@hiyve/react-ui';

function PreJoinLobby({ onJoin }: { onJoin: (devices: SelectedDevices) => void }) {
  const [devices, setDevices] = useState<SelectedDevices>({});

  return (
    <DevicePreview
      onDeviceChange={setDevices}
      onReady={() => onJoin(devices)}
      width={480}
      height={360}
    />
  );
}
Copy

Audio Level Monitoring

import { AudioLevelMonitor, GainControl } from '@hiyve/react-ui';

function AudioControls({ stream }: { stream: MediaStream }) {
  const [gain, setGain] = useState(100);

  return (
    <>
      <AudioLevelMonitor stream={stream} mode="bars" barCount={20} showPeak />
      <GainControl value={gain} onChange={setGain} label="Volume" showMuteButton />
    </>
  );
}
Copy

Tabbed Sidebar

import { Sidebar } from '@hiyve/react-ui';
import type { SidebarTab } from '@hiyve/react-ui';
import PeopleIcon from '@mui/icons-material/People';
import ChatIcon from '@mui/icons-material/Chat';

const tabs: SidebarTab[] = [
  { id: 'participants', label: 'Participants', icon: <PeopleIcon /> },
  { id: 'chat', label: 'Chat', icon: <ChatIcon />, badge: 3 },
];

function RoomSidebar() {
  const [activeTab, setActiveTab] = useState('participants');

  return (
    <Sidebar
      tabs={tabs}
      activeTab={activeTab}
      onTabChange={setActiveTab}
      renderContent={(tabId) => {
        switch (tabId) {
          case 'participants': return <ParticipantList localUserName="Me" />;
          case 'chat': return <ChatPanel />;
          default: return null;
        }
      }}
    />
  );
}
Copy

Waiting Room (Host Side)

import { WaitingRoomSetup, WaitingRoomAdmittance } from '@hiyve/react-ui';

function HostControls() {
  const [waitingEnabled, setWaitingEnabled] = useState(false);

  return (
    <>
      <WaitingRoomSetup enabled={waitingEnabled} onChange={setWaitingEnabled} />
      <WaitingRoomAdmittance
        variant="popover"
        anchorEl={anchorEl}
        open={open}
        // Service bots (recording/streaming/transcription) skip the queue:
        // they're admitted automatically and hidden from the waiting list.
        autoAdmitSystemUsers
      />
    </>
  );
}
Copy

System users are identified by a case-insensitive userId prefix match — the default list (DEFAULT_SYSTEM_USER_PREFIXES) covers recorder-/recorder_, rectrans-/rectrans_, streamer-/streamer_, and transcriber-/transcriber_ — or by the ghost-camera naming convention (a device a participant paired as a secondary camera via useRemoteCamera), which always counts as a system user. Override the prefixes via the systemUserPrefixes prop if your bots join with different ids, and use the exported isSystemWaitingUser(userId, prefixes?) to apply the same filtering to your own waiting-room UI (badges, notifications).

Invite Links

import { InviteLinkDialog } from '@hiyve/react-ui';

function ShareButton({ roomName }: { roomName: string }) {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>Share Invite Link</button>
      <InviteLinkDialog
        roomName={roomName}
        open={open}
        onClose={() => setOpen(false)}
        onCopySuccess={() => toast.success('Link copied!')}
      />
    </>
  );
}
Copy

Connecting Screen

import { ConnectingScreen } from '@hiyve/react-ui';

function RoomLoader({ isCreating }: { isCreating: boolean }) {
  return (
    <ConnectingScreen
      isCreating={isCreating}
      labels={{ creatingMessage: 'Setting up your room...', joiningMessage: 'Entering room...' }}
      colors={{ spinner: 'secondary', background: '#1a1a2e' }}
    />
  );
}
Copy

Join Form

import { JoinForm } from '@hiyve/react-ui';

// Callback mode
function LobbyPage() {
  return (
    <JoinForm
      onCreateRoom={async (roomName, userName, options) => {
        await api.createRoom(roomName, userName, options);
      }}
      onJoinRoom={async (roomName, userName) => {
        await api.joinRoom(roomName, userName);
      }}
      showWaitingRoomToggle
      showDevicePreview
      storagePrefix="myapp"
      onError={(err) => console.error(err)}
    />
  );
}

// Auto-connect mode (inside HiyveProvider)
function AutoLobby() {
  return (
    <HiyveProvider generateRoomToken={getToken}>
      <JoinForm autoConnect storagePrefix="myapp" />
    </HiyveProvider>
  );
}
Copy

Camera Management

CameraMenu provides a dropdown for managing the primary camera and adding additional cameras. It can be rendered standalone for custom control bar layouts.

import { CameraMenu } from '@hiyve/react-ui';
import type { ActiveCamera, CameraMenuProps } from '@hiyve/react-ui';

<CameraMenu
  isVideoMuted={false}
  isLocalTileHidden={false}
  selectedVideoDevice={currentDeviceId}
  videoDevices={videoDevices}
  isChangingVideoDevice={false}
  onToggleVideo={handleToggleVideo}
  onToggleLocalTile={handleToggleLocalTile}
  onVideoDeviceChange={handleDeviceChange}
  activeCameras={activeCameras}
  availableDevicesForAdd={availableDevices}
  onAddCamera={(deviceId, label) => console.log('Add camera', deviceId, label)}
  onRemoveCamera={(id) => console.log('Remove camera', id)}
  onPhoneCameraRequested={() => console.log('Phone camera requested')}
  disabled={false}
  hasClient={true}
  labels={controlBarLabels}
  icons={controlBarIcons}
  colors={controlBarColors}
  styles={controlBarStyles}
/>
Copy

Pre-Built Presentation Layout

import { VideoGrid, createPresentationLayout } from '@hiyve/react-ui';

const layout = createPresentationLayout({ thumbnailPosition: 'right', thumbnailSize: 160 });

<VideoGrid
  localVideoElementId="local-video"
  localUserName="Me"
  layout="custom"
  customLayoutHandler={layout}
/>
Copy

Custom Layout Handler

import { VideoGrid } from '@hiyve/react-ui';
import type { CustomLayoutHandler } from '@hiyve/react-ui';

const focusLayout: CustomLayoutHandler = (info) => {
  const positions: Record<string, any> = {};
  const dominant = info.dominantSpeaker;

  info.participants.forEach((p, i) => {
    if (p.userId === dominant) {
      positions[p.userId] = { x: 0, y: 0, width: info.availableWidth * 0.75, height: info.availableHeight };
    } else {
      const sideWidth = info.availableWidth * 0.25;
      const tileHeight = info.availableHeight / (info.totalCount - 1);
      positions[p.userId] = { x: info.availableWidth * 0.75, y: i * tileHeight, width: sideWidth, height: tileHeight };
    }
  });
  return positions;
};

<VideoGrid
  localVideoElementId="local-video"
  localUserName="Me"
  layout="custom"
  customLayoutHandler={focusLayout}
/>
Copy

Customization

All components accept optional labels, icons, colors, and styles props for customization. Pass a partial object -- unspecified values use built-in defaults.

Labels (i18n)

import { defaultControlBarLabels, mergeControlBarLabels } from '@hiyve/react-ui';

// Partial override
<ControlBar
  labels={{
    mute: 'Couper le micro',
    unmute: 'Activer le micro',
    leave: 'Quitter',
    shareScreen: 'Partager',
  }}
/>

// Programmatic merge
const frenchLabels = mergeControlBarLabels({
  mute: 'Couper le micro',
  unmute: 'Activer le micro',
});
Copy

Icons

import { defaultControlBarIcons, mergeControlBarIcons } from '@hiyve/react-ui';
import MyMicIcon from './MyMicIcon';

<ControlBar icons={{ mute: <MyMicIcon /> }} />
Copy

Colors

import { defaultVideoGridColors, defaultVideoTileColors } from '@hiyve/react-ui';

<VideoGrid
  colors={{ dominantBorder: '#00ff88' }}
  tileColors={{
    ...defaultVideoTileColors,
    background: '#111133',
    dominantBorder: '#00ff88',
  }}
/>

<ControlBar
  colors={{
    background: 'rgba(0, 0, 0, 0.9)',
    buttonActive: '#0066cc',
    leaveButton: '#ff3333',
  }}
/>
Copy

Styles

<ControlBar
  styles={{
    gap: 12,
    padding: 16,
    buttonSize: 'large',
    borderRadius: 8,
  }}
/>

<VideoGrid
  styles={{
    padding: 16,
    gap: 8,
    transitionDuration: '0.5s',
  }}
/>
Copy

Render Props

Advanced components support render props for custom rendering:

<VideoGrid
  renderProps={{
    renderTile: (participant, defaultTile) => (
      <div className="custom-wrapper">{defaultTile}</div>
    ),
  }}
/>
Copy

ControlBar exposes two slots for injecting your own controls — renderExtraControls (in the main cluster, before the leave button) and renderSidebarAdjacentControls (in the trailing group, immediately left of the sidebar toggle):

<ControlBar
  onSidebarToggle={toggleSidebar}
  renderProps={{
    renderExtraControls: () => <MyReactionButton />,
    renderSidebarAdjacentControls: () => <MyPanelToggle />,
  }}
/>
Copy

Available Default/Merge Exports

Each component area exports default* objects and merge* functions:

// VideoGrid
import { defaultVideoGridColors, mergeVideoGridColors } from '@hiyve/react-ui';

// VideoTile
import { defaultVideoTileLabels, mergeVideoTileLabels } from '@hiyve/react-ui';
import { defaultVideoTileColors, mergeVideoTileColors } from '@hiyve/react-ui';

// ControlBar
import { defaultControlBarLabels, mergeControlBarLabels } from '@hiyve/react-ui';
import { defaultControlBarColors, mergeControlBarColors } from '@hiyve/react-ui';
import { defaultControlBarIcons, mergeControlBarIcons } from '@hiyve/react-ui';

// DeviceSelector / DevicePreview
import { defaultDeviceSelectorLabels, mergeDeviceSelectorLabels } from '@hiyve/react-ui';
import { defaultDevicePreviewLabels, mergeDevicePreviewLabels } from '@hiyve/react-ui';

// ParticipantList
import { defaultParticipantListLabels, mergeParticipantListLabels } from '@hiyve/react-ui';

// Sidebar
import { defaultSidebarLabels, mergeSidebarLabels } from '@hiyve/react-ui';
import { defaultSidebarColors, mergeSidebarColors } from '@hiyve/react-ui';

// WaitingRoom
import { defaultSetupLabels, mergeSetupLabels } from '@hiyve/react-ui';
import { defaultAdmittanceLabels, mergeAdmittanceLabels } from '@hiyve/react-ui';
import { defaultGuestLabels, mergeGuestLabels } from '@hiyve/react-ui';

// ConnectingScreen
import { defaultConnectingScreenLabels, mergeConnectingScreenLabels } from '@hiyve/react-ui';
import { defaultConnectingScreenColors, mergeConnectingScreenColors } from '@hiyve/react-ui';
import { defaultConnectingScreenStyles, mergeConnectingScreenStyles } from '@hiyve/react-ui';

// JoinForm
import { defaultJoinFormLabels, mergeJoinFormLabels } from '@hiyve/react-ui';
import { defaultJoinFormIcons, mergeJoinFormIcons } from '@hiyve/react-ui';
import { defaultJoinFormColors, mergeJoinFormColors } from '@hiyve/react-ui';
import { defaultJoinFormStyles, mergeJoinFormStyles } from '@hiyve/react-ui';

// JoinToken
import { defaultDialogLabels, mergeDialogLabels } from '@hiyve/react-ui';
import { defaultFormLabels, mergeFormLabels } from '@hiyve/react-ui';

// UpdateBanner
import { defaultUpdateBannerLabels, mergeUpdateBannerLabels } from '@hiyve/react-ui';

// PhoneCameraDialog
import { defaultPhoneCameraDialogLabels, mergePhoneCameraDialogLabels } from '@hiyve/react-ui';
Copy

Device Persistence

Save and restore device selections across sessions. The default storage key is available as DEFAULT_DEVICE_STORAGE_KEY if you need to coordinate with other storage logic.

import { useSavedDevices, saveDevices, loadDevices, clearSavedDevices } from '@hiyve/react-ui';

function DeviceSettings() {
  const savedDevices = useSavedDevices();
  // savedDevices = { videoInput?: string, audioInput?: string, audioOutput?: string }
}
Copy

Features

• Video grid with grid, speaker, sidebar, and custom layout modes
• Smooth CSS transitions when layout changes
• Dominant speaker highlighting and hand raise badges
• Recording/streaming status indicators and timers
• Media controls with audio, video, and screen share toggles
• Device selection menus for camera, microphone, and speaker
• Live device preview with audio level monitoring
• Device persistence across sessions
• Real-time audio level visualization (bars, waveform, meter)
• Gain control with mute button
• Participant list with owner controls (remote mute, remove)
• Collapsible tabbed sidebar for content panels
• Waiting room with host setup, guest waiting screen, and admittance controls
• Invite link creation and token-based room joining
• Full i18n support through label overrides on every component
• Icon, color, and style theming on every component
• Render props for advanced customization
• Responsive layouts that adapt to container size

Requirements

• Must be used inside a HiyveProvider from @hiyve/react
• React 18+
• MUI v5 or v6 (@mui/material, @mui/icons-material) with Emotion
• @hiyve/rtc-client and @hiyve/utilities as peer dependencies
• @hiyve/react-intelligence (optional) -- required only for IntelligenceSettings

License

Proprietary - Hiyve SDK