@hiyve/react-rooms

Room management components for Hiyve — manage persistent rooms and discover live rooms in real-time, with fully customizable labels, icons, colors, and styles.

Installation

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

Quick Start

import { RoomsList } from '@hiyve/react-rooms';
import { HiyveProvider } from '@hiyve/react';

function Dashboard() {
  return (
    <HiyveProvider generateRoomToken={getToken}>
      <RoomsList
        userId="user-123"
        onStartRoom={(room) => navigate(`/room/${room.roomName}`)}
        onCreateRoom={(room) => console.log('Created:', room.alias)}
      />
    </HiyveProvider>
  );
}
Copy

Features

• Full CRUD — Create, list, edit, and delete persistent rooms
• Live room discovery — Real-time active room list via SSE (Server-Sent Events)
• Custom entity names — Rebrand "Room" to "Workspace", "Session", "Channel", etc.
• Search, sort, and filter — Client-side search by name, sort by date/name, filter by features
• Static and link-based rooms — Support both name-based and URL-based room joining
• Room features — Password protection, waiting room, offline mode toggles
• Render props — Replace individual layout sections (search bar, grid, create button, empty state) while keeping orchestration logic
• Fully customizable — Labels, icons, colors, and styles all accept partial overrides
• i18n-ready — Every string is customizable via label props

Components

Stored Rooms

Room Detail

Active Room Discovery

Hook

RoomsList Props

Entity Labels (Rebranding)

The core customization point. Set entity labels once, and all components update their text accordingly.

import { RoomsList } from '@hiyve/react-rooms';

// Rebrand as workspaces
<RoomsList
  userId="user-1"
  labels={{
    entity: {
      entity: 'Workspace',
      entityPlural: 'Workspaces',
      createEntity: 'Create Workspace',
      noEntities: 'No workspaces yet',
      deleteEntity: 'Delete Workspace',
      editEntity: 'Edit Workspace',
      searchEntities: 'Search workspaces',
    },
  }}
  onStartRoom={(room) => navigate(`/workspace/${room.roomName}`)}
/>

// Rebrand as sessions
<RoomsList
  userId="host-1"
  labels={{
    entity: {
      entity: 'Session',
      entityPlural: 'Sessions',
      createEntity: 'Schedule Session',
      noEntities: 'No sessions scheduled',
    },
  }}
/>
Copy

Customization

Every component supports customization through labels, icons, colors, and styles props. Pass a partial object to override only the values you need — unspecified keys use defaults.

Labels

import { RoomsList } from '@hiyve/react-rooms';

<RoomsList
  userId="user-123"
  labels={{
    entity: { entity: 'Meeting', entityPlural: 'Meetings' },
    card: { startButton: 'Join Now', linkCopied: 'Copied!' },
    searchBar: { searchPlaceholder: 'Find meetings...' },
    createDialog: { title: 'New Meeting', createButton: 'Schedule' },
    settingsDialog: { title: 'Meeting Options', saveButton: 'Update' },
  }}
/>
Copy

Colors

import { RoomsList } from '@hiyve/react-rooms';

// Dark theme
<RoomsList
  userId="user-123"
  colors={{
    card: {
      background: '#1e1e1e',
      border: '#333',
      hoverBackground: '#2a2a2a',
      headerBackground: '#252525',
    },
  }}
/>
Copy

Icons

import { RoomsList } from '@hiyve/react-rooms';
import { Rocket, Trash2, Cog } from 'lucide-react';

<RoomsList
  userId="user-123"
  icons={{
    card: {
      startIcon: <Rocket size={18} />,
      deleteIcon: <Trash2 size={18} />,
      settingsIcon: <Cog size={18} />,
    },
    searchBar: {
      searchIcon: <Search size={18} />,
    },
  }}
/>
Copy

Styles (MUI sx)

import { RoomsList } from '@hiyve/react-rooms';

<RoomsList
  userId="user-123"
  styles={{
    card: {
      card: { borderRadius: 3, boxShadow: 2 },
      header: { py: 1.5 },
      actions: { justifyContent: 'flex-start' },
    },
  }}
/>
Copy

Custom Empty State

import { RoomsList } from '@hiyve/react-rooms';
import { Box, Typography } from '@mui/material';

<RoomsList
  userId="user-123"
  emptyStateContent={
    <Box textAlign="center" py={6}>
      <Typography variant="h6">Welcome!</Typography>
      <Typography color="text.secondary">
        Create your first room to get started.
      </Typography>
    </Box>
  }
/>
Copy

Render Props

Replace individual layout sections while keeping all orchestration logic (data fetching, dialog management, CRUD handlers) intact. Each render function receives the relevant state and action handlers.

Available Render Props

Dialogs (create, settings, delete) are always managed internally — render props only affect layout sections.

List Layout

import { RoomsList } from '@hiyve/react-rooms';
import { List, ListItem, ListItemText, IconButton } from '@mui/material';
import { PlayArrow, Settings, Delete } from '@mui/icons-material';

<RoomsList
  userId="user-123"
  onStartRoom={handleStart}
  renderProps={{
    renderGrid: ({ rooms, onStart, onSelect, onSettings, onDelete }) => (
      <List>
        {rooms.map((room) => (
          <ListItem
            key={room.alias}
            onClick={() => onSelect(room)}
            secondaryAction={
              <>
                <IconButton onClick={() => onSettings(room)}><Settings /></IconButton>
                <IconButton onClick={() => onDelete(room)}><Delete /></IconButton>
              </>
            }
          >
            <ListItemText primary={room.alias} secondary={room.roomName} />
            <IconButton onClick={() => onStart(room)}><PlayArrow /></IconButton>
          </ListItem>
        ))}
      </List>
    ),
  }}
/>
Copy

Floating Action Button

import { Fab } from '@mui/material';
import { Add } from '@mui/icons-material';

<RoomsList
  userId="user-123"
  renderProps={{
    renderCreateButton: ({ onCreate, entityLabels }) => (
      <Fab color="primary" onClick={onCreate} sx={{ position: 'fixed', bottom: 24, right: 24 }}>
        <Add />
      </Fab>
    ),
  }}
/>
Copy

Custom Search

import { RoomsList } from '@hiyve/react-rooms';
import { TextField } from '@mui/material';

<RoomsList
  userId="user-123"
  renderProps={{
    renderSearchBar: ({ searchQuery, setSearchQuery, totalRooms }) => (
      <TextField
        fullWidth
        placeholder={`Search ${totalRooms} rooms...`}
        value={searchQuery}
        onChange={(e) => setSearchQuery(e.target.value)}
      />
    ),
  }}
/>
Copy

Precedence

• renderSearchBar ignores the showSearchBar boolean (still gated by rooms.length > 0)
• renderCreateButton ignores the showCreateButton boolean
• renderEmptyState ignores the emptyStateContent ReactNode
• renderGrid replaces the entire default grid

RoomDetailHeader

A banner card for displaying room details with a gradient header, title, optional category badge, stats row, and action buttons. Suitable for room detail pages or dashboards.

import { RoomDetailHeader } from '@hiyve/react-rooms';
import GroupIcon from '@mui/icons-material/Group';
import FolderIcon from '@mui/icons-material/Folder';
import { Button } from '@mui/material';

function RoomDetail({ room }) {
  return (
    <RoomDetailHeader
      room={room}
      headerGradient={['#5d6b82', '#3d4a5c']}
      categoryBadge={{ label: 'Team' }}
      stats={[
        { icon: <GroupIcon fontSize="small" />, label: 'Members', value: '12' },
        { icon: <FolderIcon fontSize="small" />, label: 'Files', value: '45' },
      ]}
      actions={<Button variant="contained">Start</Button>}
    />
  );
}
Copy

RoomDetailHeader Props

RoomDetailStat

Active Room Discovery

Guests can discover and join live rooms in real-time using targeted discovery. Room owners advertise their rooms via @hiyve/cloud and specify which users can see them. Only targeted users receive room events through the SSE stream.

Every advertised room requires a targetUserIds array — there is no broadcast mode. This ensures rooms are only visible to their intended audience.

Quick Start

import { ActiveRoomsList } from '@hiyve/react-rooms';
import { HiyveProvider } from '@hiyve/react';
import { CloudClient } from '@hiyve/cloud';

const cloudClient = new CloudClient({ cloudToken: 'ct_your_token' });
const userId = 'guest-1';

function Lobby() {
  const [streamUrl, setStreamUrl] = useState<string>();

  useEffect(() => {
    cloudClient.getActiveRoomsStreamUrl(userId).then(setStreamUrl);
  }, []);

  if (!streamUrl) return null;

  return (
    <HiyveProvider generateRoomToken={getToken}>
      <ActiveRoomsList
        streamUrl={streamUrl}
        onJoinRoom={(room) => store.joinRoom(room.name, userId)}
      />
    </HiyveProvider>
  );
}
Copy

Owner: Advertise a Room

import { CloudClient } from '@hiyve/cloud';

const cloudClient = new CloudClient({ cloudToken: 'ct_your_token' });

// After creating a room, advertise it to specific users
await store.createRoom('Team Standup', userId);
await cloudClient.advertiseRoom({
  name: 'Team Standup',
  ownerDisplayName: 'Karl',
  targetUserIds: ['guest-1', 'guest-2', 'guest-3'],
  metadata: { waitingRoom: true },
});

// Update who can see the room (e.g., add a late invitee)
await cloudClient.updateAdvertisedRoom('Team Standup', {
  targetUserIds: ['guest-1', 'guest-2', 'guest-3', 'guest-4'],
});

// When leaving, remove from discovery
await store.leaveRoom();
await cloudClient.removeAdvertisedRoom('Team Standup');
Copy

One-Shot Fetch

Use getActiveRooms for a one-time query instead of a live stream:

// Fetch rooms targeted at a specific user
const rooms = await cloudClient.getActiveRooms(userId);

// Or fetch all rooms for the org (no userId filter)
const allRooms = await cloudClient.getActiveRooms();
Copy

ActiveRoomsList Props

ActiveRoomCard Props

Custom Card Rendering

import { ActiveRoomsList } from '@hiyve/react-rooms';
import { Button, Typography, Paper } from '@mui/material';

<ActiveRoomsList
  streamUrl={streamUrl}
  onJoinRoom={handleJoin}
  renderCard={(room, onJoin) => (
    <Paper sx={{ p: 2 }}>
      <Typography variant="h6">{room.name}</Typography>
      <Typography color="text.secondary">
        by {room.ownerDisplayName || room.owner}
      </Typography>
      <Button onClick={() => onJoin?.(room)}>Join</Button>
    </Paper>
  )}
/>
Copy

Customizing Labels

<ActiveRoomsList
  streamUrl={streamUrl}
  onJoinRoom={handleJoin}
  labels={{
    title: 'Live Sessions',
    emptyState: 'No sessions running right now',
    searchPlaceholder: 'Find a session...',
  }}
  cardLabels={{
    joinButton: 'Enter',
    liveIndicator: 'In Progress',
    hostedBy: 'Led by',
  }}
/>
Copy

Active Room Discovery Defaults

Standalone Components

All components can be used individually for custom layouts:

import {
  RoomCard,
  RoomSearchBar,
  CreateRoomDialog,
  useRoomFilters,
} from '@hiyve/react-rooms';
import { useStoredRooms } from '@hiyve/react';

function CustomRoomGrid() {
  const { rooms, fetchStoredRooms, addStoredRoom } = useStoredRooms();
  const { searchQuery, setSearchQuery, sortBy, setSortBy,
    filterBy, setFilterBy, processedRooms, clearFilters,
    activeFiltersCount } = useRoomFilters(rooms);
  const [createOpen, setCreateOpen] = useState(false);

  useEffect(() => { fetchStoredRooms('user-123'); }, []);

  return (
    <>
      <RoomSearchBar
        searchQuery={searchQuery}
        sortBy={sortBy}
        filterBy={filterBy}
        onSearchChange={setSearchQuery}
        onSortChange={setSortBy}
        onFilterChange={setFilterBy}
        onClear={clearFilters}
        activeFiltersCount={activeFiltersCount}
      />
      {processedRooms.map((room) => (
        <RoomCard
          key={room.id}
          room={room}
          onStart={(r) => joinRoom(r.roomName)}
        />
      ))}
      <CreateRoomDialog
        open={createOpen}
        onClose={() => setCreateOpen(false)}
        onSave={async (opts) => {
          await addStoredRoom(opts, 'user-123');
          setCreateOpen(false);
        }}
      />
    </>
  );
}
Copy

Defaults and Merge Functions

All defaults are exported for consumers who want to extend or reference them:

Entity Labels:

Component Labels:

Icons and Colors:

Room Detail Header:

Factory functions accept entity labels and generate defaults dynamically -- so createDefaultCardLabels({ entity: 'Workspace', ... }) produces startButton: 'Start Workspace' automatically.

Both SCREAMING_SNAKE_CASE and camelCase aliases reference the same objects. Use whichever naming convention matches your codebase.

Static vs Link-Based Rooms

Rooms support two join modes:

• Link-based (default) — Rooms get a generated join URL. Users join via the link.
• Static — Rooms use a fixed name. Users join by entering the room name directly.

// Show the static room option in the create dialog
<RoomsList
  userId="user-123"
  showStaticOption={true}
  onStartRoom={(room) => {
    if (room.roomLink) {
      // Link-based: navigate to join URL
      window.location.href = room.roomLink;
    } else {
      // Static: join by name
      joinRoom(room.roomName);
    }
  }}
/>
Copy

Static rooms display a "Static" badge chip, while link-based rooms show a "Link" badge. The "Copy Link" action is only available for link-based rooms.

Requirements

• @hiyve/react (^2.0.0) — components must be rendered inside HiyveProvider
• @hiyve/core (^1.0.0) — state store types and StoredRoom interface
• @hiyve/cloud (^1.0.0) — required for active room discovery (CloudClient)
• @hiyve/rtc-client — WebRTC client (provided by HiyveProvider)
• @hiyve/utilities (^1.0.0)
• @mui/material (^5.0.0 || ^6.0.0) and @mui/icons-material
• @emotion/react (>=11) and @emotion/styled (>=11)
• react (^18.0.0)

License

Proprietary - Hiyve SDK