Hiyve Components - v1.0.0
    Preparing search index...

    Interface VideoGridProps

    Props for the VideoGrid component.

    VideoGrid is a container component that manages the layout of video tiles for a video conferencing session. Must be used inside a <HiyveProvider>.

    It automatically handles:

    • Local video tile placement
    • Remote participant tile arrangement (from context)
    • Layout transitions between grid, speaker, and sidebar modes
    • Dominant speaker highlighting (from context)
    • Recording/streaming indicators (from context)
    • Mood analysis display (from MoodAnalysisProvider if available)
    • Responsive resizing

    The component uses absolute positioning to prevent video element remounting when the layout changes, ensuring smooth transitions.

    Basic usage inside HiyveProvider:

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

    function VideoRoom() {
      return (
        <HiyveProvider client={client} roomName={roomName} userId={userId}>
          <VideoGrid
            localVideoElementId="local-video"
            localUserName="Me"
            layout="grid"
            showLocalFlip={true}
            showMuteIndicators={true}
          />
        </HiyveProvider>
      );
    }

    Speaker mode with timer:

    <VideoGrid
      localVideoElementId="local-video"
      localUserName="Presenter"
      layout="speaker"
      showTimer
    />
    interface VideoGridProps {
        colors?: Partial<VideoGridColors>;
        controlPosition?: OverlayPosition;
        controlsLayout?: "icons" | "menu";
        customLayoutHandler?: CustomLayoutHandler;
        engagementPosition?: OverlayPosition;
        gap?: number;
        hideLocalTile?: boolean;
        indicatorPosition?: OverlayPosition;
        labelPosition?: OverlayPosition;
        layout?: string;
        localTileColors?: Partial<LocalVideoTileColors>;
        localTileIcons?: Partial<LocalVideoTileIcons>;
        localTileLabels?: Partial<LocalVideoTileLabels>;
        localTileOverlayOrder?: LocalVideoTileOverlayElement[];
        localTileRenderProps?: LocalVideoTileRenderProps;
        localTileStyles?: Partial<LocalVideoTileStyles>;
        localUserName?: string;
        localVideoElementId: string;
        minTileWidth?: number;
        moodPosition?: OverlayPosition;
        onError?: (error: Error) => void;
        onLocalClick?: () => void;
        onMuteParticipantAudio?: (userId: string, muted: boolean) => void;
        onMuteParticipantVideo?: (userId: string, muted: boolean) => void;
        onParticipantClick?: (userId: string) => void;
        onToggleAudio?: () => void;
        onToggleHideSelf?: () => void;
        onToggleVideo?: () => void;
        participants?: Participant[];
        renderProps?: VideoGridRenderProps;
        resolveDisplayName?: (
            userId: string,
            defaultName: string,
        ) => string | null | undefined;
        screenSharingUserIds?: readonly string[];
        showEngagement?: boolean;
        showFit?: boolean;
        showHideSelf?: boolean;
        showLocalFlip?: boolean;
        showMood?: boolean;
        showMuteAudio?: boolean;
        showMuteIndicators?: boolean;
        showMuteParticipantAudio?: boolean;
        showMuteParticipantVideo?: boolean;
        showMuteVideo?: boolean;
        showNames?: boolean;
        showTimer?: boolean;
        showZoom?: boolean;
        statusPosition?: OverlayPosition;
        styles?: Partial<VideoGridStyles>;
        sx?: SxProps<Theme>;
        tileColors?: Partial<VideoTileColors>;
        tileIcons?: Partial<VideoTileIcons>;
        tileLabels?: Partial<VideoTileLabels>;
        tileOverlayOrder?: VideoTileOverlayElement[];
        tileRenderProps?: VideoTileRenderProps;
        tileStyles?: Partial<VideoTileStyles>;
        timerPosition?: OverlayPosition;
    }
    Index

    Properties

    colors? controlPosition? controlsLayout? customLayoutHandler? engagementPosition? gap? hideLocalTile? indicatorPosition? labelPosition? layout? localTileColors? localTileIcons? localTileLabels? localTileOverlayOrder? localTileRenderProps? localTileStyles? localUserName? localVideoElementId minTileWidth? moodPosition? onError? onLocalClick? onMuteParticipantAudio? onMuteParticipantVideo? onParticipantClick? onToggleAudio? onToggleHideSelf? onToggleVideo? participants? renderProps? resolveDisplayName? screenSharingUserIds? showEngagement? showFit? showHideSelf? showLocalFlip? showMood? showMuteAudio? showMuteIndicators? showMuteParticipantAudio? showMuteParticipantVideo? showMuteVideo? showNames? showTimer? showZoom? statusPosition? styles? sx? tileColors? tileIcons? tileLabels? tileOverlayOrder? tileRenderProps? tileStyles? timerPosition?

    Properties

    colors?: Partial<VideoGridColors>

    Custom colors for the VideoGrid container.

    VideoGridColors for available options.

    controlPosition?: OverlayPosition

    Position of control buttons (flip, zoom) on local tile.

    'bottom-right'
    controlsLayout?: "icons" | "menu"

    Forwarded to every tile (local and remote). Default 'icons' keeps each control as its own button in the overlay; 'menu' collapses them into a single overflow trigger rendered next to the tile's name caption. Useful for tight grids / mobile.

    'icons'
    customLayoutHandler?: CustomLayoutHandler

    Custom layout handler for implementing custom layout modes.

    When the layout prop is not one of the built-in modes ('grid', 'speaker', 'sidebar'), this handler is called to calculate tile positions. If no handler is provided for a custom layout, the grid layout is used as a fallback.

    // "Focus" layout - large center tile with small corners
    const focusLayout: CustomLayoutHandler = ({ availableWidth, availableHeight, participants, padding }) => {
      const positions: Record<string, TilePosition> = {};
      const cornerSize = 120;

      // Local user in large center area
      positions['local'] = {
        left: padding + cornerSize,
        top: padding + cornerSize,
        width: availableWidth - cornerSize * 2,
        height: availableHeight - cornerSize * 2,
      };

      // Participants in corners
      const corners = [
        { left: padding, top: padding },
        { left: padding + availableWidth - cornerSize, top: padding },
        { left: padding, top: padding + availableHeight - cornerSize },
        { left: padding + availableWidth - cornerSize, top: padding + availableHeight - cornerSize },
      ];

      participants.forEach((p, i) => {
        if (i < corners.length) {
          positions[p.userId] = {
            ...corners[i],
            width: cornerSize,
            height: cornerSize,
          };
        }
      });

      return positions;
    };

    <VideoGrid
      layout="focus"
      customLayoutHandler={focusLayout}
    />
    engagementPosition?: OverlayPosition

    Position of engagement indicator on video tiles.

    'top-left'
    gap?: number

    Gap between tiles in pixels.

    8
    hideLocalTile?: boolean

    Hide the local video tile from the grid. When true, the local tile is hidden (display: none) but remains in the DOM so the video element stays attached for WebRTC streaming. Remote participants still see the local user's video.

    false
    indicatorPosition?: OverlayPosition

    Position of recording/streaming indicator on local tile.

    'top-left'
    labelPosition?: OverlayPosition

    Position of name labels on tiles.

    'bottom-left'
    layout?: string

    Layout mode for arranging video tiles.

    'grid'

    LayoutMode for available modes.

    localTileColors?: Partial<LocalVideoTileColors>

    Custom colors for the local VideoTile component. Includes overlay, recording indicator, and mute colors.

    localTileIcons?: Partial<LocalVideoTileIcons>

    Custom icons for the local VideoTile component. Replace default flip, fullscreen, and record icons.

    localTileLabels?: Partial<LocalVideoTileLabels>

    Custom labels for the local VideoTile component. Use for i18n/localization of control tooltips.

    localTileOverlayOrder?: LocalVideoTileOverlayElement[]

    Render order for overlay elements on the local tile when they share the same position. Elements listed first appear first (leftmost for horizontal layouts).

    ['indicator', 'timer', 'engagement', 'mood', 'name', 'status', 'controls']
    localTileRenderProps?: LocalVideoTileRenderProps

    Render props for the local VideoTile component. Allows custom overlay and duration formatting.

    localTileStyles?: Partial<LocalVideoTileStyles>

    Custom styles for the local VideoTile component. Controls button sizing, animation, and typography.

    localUserName?: string

    Display name for the local user. Shown on the local video tile with "(You)" suffix.

    localVideoElementId: string

    HTML element ID for the local video element. This ID must match the one used when calling client.connectTransports().

    Hiyve client attaches the local video stream to an element with this ID. The VideoGrid creates the video element internally.

    // In your component
    <VideoGrid localVideoElementId="local-video" />

    // When connecting Hiyve
    await client.connectTransports({
      localVideoElementId: 'local-video',
    });
    minTileWidth?: number

    Minimum tile width in pixels. Used to calculate grid columns in auto-layout mode.

    200
    moodPosition?: OverlayPosition

    Position of mood indicator on video tiles.

    'top-left'
    onError?: (error: Error) => void

    Callback when an error occurs during grid rendering

    onLocalClick?: () => void

    Callback when the local tile is clicked.

    onMuteParticipantAudio?: (userId: string, muted: boolean) => void

    Called when a remote participant's mute-audio menu item is clicked. Receives the participant's userId and the desired muted state (the negation of their current isMuted.audio). Wire this to useRemoteMute().remoteMuteAudio.

    onMuteParticipantVideo?: (userId: string, muted: boolean) => void

    Called when a remote participant's mute-video menu item is clicked. Receives the participant's userId and the desired muted state. Wire this to useRemoteMute().remoteMuteVideo.

    onParticipantClick?: (userId: string) => void

    Callback when a remote participant's tile is clicked.

    Type Declaration

      • (userId: string): void

      • Parameters

        • userId: string

          The clicked participant's user ID

        Returns void

    onToggleAudio?: () => void

    Toggle the local user's audio mute. Forwarded to LocalVideoTile.

    onToggleHideSelf?: () => void

    Toggle whether the local tile is hidden. Forwarded to LocalVideoTile.

    onToggleVideo?: () => void

    Toggle the local user's video mute. Forwarded to LocalVideoTile.

    participants?: Participant[]

    Override the participants array (otherwise derived from HiyveProvider context). Use this when you need full control over which participants are displayed.

    Participant for the required data structure.

    renderProps?: VideoGridRenderProps

    Render props for advanced VideoGrid customization.

    VideoGridRenderProps for available render functions.

    resolveDisplayName?: (
        userId: string,
        defaultName: string,
    ) => string | null | undefined

    Resolve a display name for a participant. Called with the userId and the SDK-resolved name (from userName/externalUserId). Return a custom name (e.g., a nickname) or null/undefined to use the default.

    <VideoGrid
      resolveDisplayName={(userId, defaultName) =>
        nicknames[userId] || defaultName
      }
    />
    screenSharingUserIds?: readonly string[]

    IDs of participants currently sharing their screen (including the local user when sharing). Used by the 'screenshare' built-in layout to pick the prominent tile: the dominant speaker is preferred when they're sharing; otherwise the first ID in this array. When the layout is anything other than 'screenshare' this prop is ignored.

    import { useScreenSharingParticipants } from '@hiyve/react-annotations';
    const sharers = useScreenSharingParticipants();
    <VideoGrid
      layout="screenshare"
      screenSharingUserIds={sharers.map((p) => p.userId)}
    />
    showEngagement?: boolean

    Show engagement indicators on video tiles. Requires MoodAnalysisProvider to be available.

    false
    showFit?: boolean

    Show fit/fill toggle button on video tiles.

    false
    showHideSelf?: boolean

    Show the "Hide self / Show self" item in the local tile's overflow menu. Requires controlsLayout === 'menu' and onToggleHideSelf. The grid's hideLocalTile prop drives the actual visibility — the menu just reports the user's intent.

    false
    showLocalFlip?: boolean

    Show the flip/mirror button on the local video tile.

    true
    showMood?: boolean

    Show mood indicators on video tiles. When undefined, automatically enabled if MoodAnalysisProvider is available and enabled.

    undefined (auto-detect)
    showMuteAudio?: boolean

    Show the "Mute / Unmute audio" item in the local tile's overflow menu. Requires controlsLayout === 'menu' and onToggleAudio to have an effect — same callback semantics as ControlBar.

    false
    showMuteIndicators?: boolean

    Show mute status indicators (mic/camera icons).

    true
    showMuteParticipantAudio?: boolean

    Show the "Mute / Unmute audio" item in each remote participant tile's overflow menu. Requires onMuteParticipantAudio. Intended for room owners — the consumer decides whether to enable it (typically isOwner && controlsLayout === 'menu').

    false
    showMuteParticipantVideo?: boolean

    Show the "Mute / Unmute video" item in each remote participant tile's overflow menu. Requires onMuteParticipantVideo.

    false
    showMuteVideo?: boolean

    Show the "Mute / Unmute video" item in the local tile's overflow menu. Requires controlsLayout === 'menu' and onToggleVideo.

    false
    showNames?: boolean

    Show participant names on video tiles.

    true
    showTimer?: boolean

    Show room duration timer on local tile. Timer starts from when the room was created (from context).

    false
    showZoom?: boolean

    Show the fullscreen/zoom button on video tiles.

    false
    statusPosition?: OverlayPosition

    Position of status indicators (mute, hand raised) on remote tiles.

    'top-right'
    styles?: Partial<VideoGridStyles>

    Custom styles for VideoGrid layout.

    VideoGridStyles for available options.

    sx?: SxProps<Theme>

    MUI sx prop for additional styling on the container.

    tileColors?: Partial<VideoTileColors>

    Custom colors for remote VideoTile components. Includes avatar palette, indicator colors, etc.

    tileIcons?: Partial<VideoTileIcons>

    Custom icons for remote VideoTile components. Replace default Material-UI icons with custom ones.

    tileLabels?: Partial<VideoTileLabels>

    Custom labels for remote VideoTile components. Use for i18n/localization of tooltip text.

    tileOverlayOrder?: VideoTileOverlayElement[]

    Render order for overlay elements on remote tiles when they share the same position. Elements listed first appear first (leftmost for horizontal layouts).

    ['engagement', 'mood', 'name', 'status', 'controls']
    tileRenderProps?: VideoTileRenderProps

    Render props for remote VideoTile components. Allows custom avatar and overlay rendering.

    tileStyles?: Partial<VideoTileStyles>

    Custom styles for remote VideoTile components. Controls spacing, sizing, and typography.

    timerPosition?: OverlayPosition

    Position of timer on local tile.

    'top-right'

    Settings

    Member Visibility

    On This Page

    Properties