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

    Interface WhiteboardProps

    Main Whiteboard component props

    interface WhiteboardProps {
        backgroundFiles?: {
            fileId: string;
            fileName: string;
            resourceType: string;
        }[];
        canvasSx?: SxProps<Theme>;
        colors?: Partial<WhiteboardColors>;
        currentColor?: string;
        currentTool?: WhiteboardTool;
        currentWidth?: number;
        defaultColor?: string;
        defaultTool?: WhiteboardTool;
        defaultWidth?: number;
        enableAddins?: boolean;
        enableAutoSave?: boolean;
        enabledAddins?: string[];
        fileId: string;
        fileOwner?: string;
        icons?: Partial<WhiteboardIcons>;
        initialFileData?: WhiteboardFile;
        isOwner?: boolean;
        labels?: Partial<WhiteboardLabels>;
        localUserLabel?: string;
        onAuditEventsChange?: (events: WhiteboardAuditEntry[]) => void;
        onCanvasCleared?: () => void;
        onClose?: () => void;
        onColorChange?: (color: string) => void;
        onError?: (error: Error) => void;
        onGetFileUrl?: (file: { fileId: string }) => Promise<string | null>;
        onObjectAdded?: (object: WhiteboardObject) => void;
        onObjectModified?: (object: WhiteboardObject) => void;
        onObjectRemoved?: (objectId: string) => void;
        onOpenFilePicker?: () => void;
        onReadOnlyChange?: (readOnly: boolean) => void;
        onSave?: (data: WhiteboardFile) => Promise<void>;
        onSnapshot?: (blob: Blob) => void;
        onSymbolAdded?: (symbol: WhiteboardSymbol) => void;
        onTitleChange?: (title: string) => void;
        onToolChange?: (tool: WhiteboardTool) => void;
        onUnsavedChangesChange?: (hasUnsavedChanges: boolean) => void;
        onUploadBackgroundFile?: (
            file: File,
        ) => Promise<
            { fileId: string; fileName: string; resourceType: string }
            | null,
        >;
        onWidthChange?: (width: number) => void;
        peerLabels?: Map<string, string>;
        resolveDisplayName?: (
            userId: string,
            defaultName: string,
        ) => string | null | undefined;
        sharedWith?: string[];
        showGrid?: boolean;
        showToolbar?: boolean;
        showZoomControls?: boolean;
        styles?: Partial<WhiteboardStyles>;
        sx?: SxProps<Theme>;
        symbolLibrary?:
            | WhiteboardSymbolLibrary
            | (() => Promise<WhiteboardSymbolLibrary>);
        toolbarSx?: SxProps<Theme>;
    }
    Index

    Properties

    backgroundFiles? canvasSx? colors? currentColor? currentTool? currentWidth? defaultColor? defaultTool? defaultWidth? enableAddins? enableAutoSave? enabledAddins? fileId fileOwner? icons? initialFileData? isOwner? labels? localUserLabel? onAuditEventsChange? onCanvasCleared? onClose? onColorChange? onError? onGetFileUrl? onObjectAdded? onObjectModified? onObjectRemoved? onOpenFilePicker? onReadOnlyChange? onSave? onSnapshot? onSymbolAdded? onTitleChange? onToolChange? onUnsavedChangesChange? onUploadBackgroundFile? onWidthChange? peerLabels? resolveDisplayName? sharedWith? showGrid? showToolbar? showZoomControls? styles? sx? symbolLibrary? toolbarSx?

    Properties

    backgroundFiles?: { fileId: string; fileName: string; resourceType: string }[]

    Available files for background selection (images + PDFs from file manager)

    canvasSx?: SxProps<Theme>

    Additional MUI sx props for the canvas container

    colors?: Partial<WhiteboardColors>

    Custom colors for styling

    currentColor?: string

    Current drawing color (controlled mode)

    currentTool?: WhiteboardTool

    Current selected tool (controlled mode)

    currentWidth?: number

    Current stroke width (controlled mode)

    defaultColor?: string

    Default drawing color (uncontrolled mode)

    defaultTool?: WhiteboardTool

    Default tool (uncontrolled mode)

    defaultWidth?: number

    Default stroke width (uncontrolled mode)

    enableAddins?: boolean

    Enable add-in system (default: true)

    enableAutoSave?: boolean

    Enable auto-save (default: true)

    enabledAddins?: string[]

    Initial add-ins to enable

    fileId: string

    File ID of the whiteboard to load/edit

    fileOwner?: string

    The file owner's userId. Together with sharedWith, used to filter incoming broadcast messages. When omitted, sync filtering is disabled (all messages accepted — legacy behavior).

    icons?: Partial<WhiteboardIcons>

    Custom icons for UI elements

    initialFileData?: WhiteboardFile

    Initial file data for newly created whiteboards. When provided, the whiteboard will initialize with this data instead of fetching from the server. This is useful for newly created files that may not be immediately available.

    isOwner?: boolean

    Override ownership check. When true, always allows saving regardless of file owner field.

    labels?: Partial<WhiteboardLabels>

    Custom labels for UI elements

    localUserLabel?: string

    Local user's display label sent on the presence channel so peers see a readable name. Falls back to userId-derivation when omitted.

    onAuditEventsChange?: (events: WhiteboardAuditEntry[]) => void

    Called whenever the persistent audit log changes (initial seed, append on local/remote action, snapshot replace). The consumer typically holds these in state and renders a WhiteboardAuditPanel in its own UI surface (e.g. a drawer or sidebar tab). Owner-only intent is enforced by the renderer — the SDK fires this for all participants who can read the log.

    onCanvasCleared?: () => void

    Called when canvas is cleared

    onClose?: () => void

    Called when the whiteboard should close

    onColorChange?: (color: string) => void

    Callback when color changes

    onError?: (error: Error) => void

    Called when an async operation fails (file load/save, sync, duplication, etc.)

    onGetFileUrl?: (file: { fileId: string }) => Promise<string | null>

    Resolve a presigned URL for a file by its entry. Required for background import.

    onObjectAdded?: (object: WhiteboardObject) => void

    Called when an object is added

    onObjectModified?: (object: WhiteboardObject) => void

    Called when an object is modified

    onObjectRemoved?: (objectId: string) => void

    Called when an object is removed

    onOpenFilePicker?: () => void

    Optional handler for an "Open existing" affordance rendered in the title bar (left of the title field). Useful when the editor was opened on a fresh blank file and the user wants a way back to a file picker. Omit to hide the button.

    onReadOnlyChange?: (readOnly: boolean) => void

    Called when read-only state changes

    onSave?: (data: WhiteboardFile) => Promise<void>

    Called when save is triggered

    onSnapshot?: (blob: Blob) => void

    Called with a small WebP preview of the current canvas contents after every successful save and once more when the whiteboard unmounts. Use this to persist a thumbnail (e.g. in an IndexedDB cache keyed by fileId) so library/file-browser cards can show a real snapshot instead of a generic placeholder.

    The blob is generated from the logical canvas workspace (zoom/pan independent). Default size: longest edge 320px, quality 0.7.

    onSymbolAdded?: (symbol: WhiteboardSymbol) => void

    Called after a symbol has been added to the canvas.

    onTitleChange?: (title: string) => void

    Called when the whiteboard title changes

    onToolChange?: (tool: WhiteboardTool) => void

    Callback when tool changes

    onUnsavedChangesChange?: (hasUnsavedChanges: boolean) => void

    Called when unsaved changes state changes

    onUploadBackgroundFile?: (
        file: File,
    ) => Promise<
        { fileId: string; fileName: string; resourceType: string }
        | null,
    >

    Upload a new file (image or PDF) to the file system. After upload completes, the file is automatically added as a background. Required to enable the "Upload background" button in the toolbar.

    onWidthChange?: (width: number) => void

    Callback when width changes

    peerLabels?: Map<string, string>

    Optional display labels for remote peers, keyed by their userId. Consumed by the presence overlay to show readable names next to each peer's cursor instead of falling back to a hashed id. Wire this from the lesson roster (e.g. useParticipants()).

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

    Resolve a userId to a display name for the audit panel and any other surface that renders attribution. Called with the cleaned userId and a sensible default; return the canonical display name (e.g. nickname → real name → email) or undefined to fall through to the default. Matches the convention used by VideoGrid, Chat, and ParticipantList.

    Wire this from useResolveDisplayName (or equivalent app-level roster lookup) so the audit panel reads the same names a teacher sees everywhere else in the app — including peer userIds the lesson-room participant list doesn't carry (e.g. when the whiteboard is opened outside a lesson context).

    sharedWith?: string[]

    User IDs that have access to this file. Used to filter incoming broadcast messages so only the owner and shared users receive real-time edits. When empty or omitted, only the file owner's broadcasts are accepted (owner-only default). When fileOwner is also omitted, filtering is disabled entirely.

    showGrid?: boolean

    Show grid lines (default: false)

    showToolbar?: boolean

    Show the toolbar (default: true)

    showZoomControls?: boolean

    Show the zoom controls (default: true)

    styles?: Partial<WhiteboardStyles>

    Custom style configuration

    sx?: SxProps<Theme>

    Additional MUI sx props for the container

    symbolLibrary?:
        | WhiteboardSymbolLibrary
        | (() => Promise<WhiteboardSymbolLibrary>)

    Symbol library — either a pre-loaded object or an async loader called the first time the user opens the symbols popup. When provided, a symbol button appears in the toolbar.

    toolbarSx?: SxProps<Theme>

    Additional MUI sx props for the toolbar

    Settings

    Member Visibility

    On This Page

    Properties