Props Reference

Required Props

messages

• Type: TMessage[]
• Required

Array of messages in chronological order (oldest first). The component is reactive — push, splice, or reassign to update.

getMessageId

• Type: (message: TMessage) => string
• Required

Extracts a unique, stable identifier from a message. Used for height caching, keyed rendering, and scrollToMessage.

renderMessage

• Type: Snippet<[message: TMessage, index: number]>
• Required

Svelte 5 snippet that renders a single message. Receives the message object and its index in the array.

{#snippet renderMessage(message, index)}
    <div class="p-4 border-b">
        <strong>{message.role}</strong>
        <p>{message.content}</p>
    </div>
{/snippet}

{#snippet renderMessage(message, index)}
    <div class="p-4 border-b">
        <strong>{message.role}</strong>
        <p>{message.content}</p>
    </div>
{/snippet}

Optional Props

estimatedMessageHeight

• Type: number
• Default: 72

Height estimate in pixels for messages not yet measured by ResizeObserver. Affects initial layout before real heights are known. Closer estimates = less layout shift.

followBottomThresholdPx

• Type: number
• Default: 48

Distance in pixels from the bottom at which the viewport is considered “at bottom” for follow-bottom behavior. Increase this if follow-bottom is too sensitive.

overscan

• Type: number
• Default: 6

Number of extra messages to render above and below the visible viewport. Higher values = smoother scrolling but more DOM nodes.

onNeedHistory

• Type: () => void | Promise<void>

Called when the user scrolls near the top of the chat. Use this to load older messages. The component calls this once when scrollTop is within half a viewport height of the top.

onFollowBottomChange

• Type: (isFollowing: boolean) => void

Called when the follow-bottom state transitions. Use this to show a “new messages” indicator when the user scrolls away.

onDebugInfo

• Type: (info: SvelteVirtualChatDebugInfo) => void

Called on every scroll and render update with live stats. Useful for development overlays and performance monitoring.

containerClass

• Type: string
• Default: ''

CSS class for the outermost container element. Typically set to "h-full".

viewportClass

• Type: string
• Default: ''

CSS class for the scrollable viewport element. Typically set to "h-full".

debug

• Type: boolean
• Default: false

Accepted by the component type but currently unused. Included for forward compatibility — future versions may use this to enable built-in debug overlays or verbose logging.

testId

• Type: string

Base test ID for data-testid attributes. When set, each internal element gets a testid (e.g., chat-viewport, chat-container, chat-item-0).