Message List

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Renders a ChatScroll log. Props are ChatScroll's, except children and loadingRow, plus the ones below.

Prop	Type	Default	Notes
`items`	`readonly MessageListItem[]`	required	The transcript, oldest first
`variant`	`MessageVariant`	`Plain`	For every message, unless `selfVariant` says otherwise
`selfVariant`	`MessageVariant`	`variant`	For the reader's own messages (`Self`, or a `user` role)
`showAuthor`	`boolean`	`true`	Avatar and author line on every message. A message's own `showAuthor` wins
`metaPlacement`	`MessageMetaPlacement`	`Inline`	Where a message's time and metadata sit in its author line. A message's own wins
`emptyIcon`	`Glyph`		Glyph in the empty state's icon well
`emptyTitle`	`LocalizedMessage`	required	Empty state title
`emptyDescription`	`LocalizedMessage \| DisplayValue`		Empty state description
`loading`	`boolean`	`false`	Placeholder lines at the top; with `loadingLabel`
`loadingLabel`	`LocalizedMessage`	required with `loading`	Announced once when loading starts

From ChatScroll: label (required), jumpToLatestLabel (required), jumpUnreadLabel, unreadCount, errorRow, onReachStart, onAtEndChange, overlay, ref, and native div attributes except those ChatScroll owns.

Items

The sender of an item is its resolved side (author, or the from role) with its name (authorName, or the identity name); a Block has author and authorName. A System item has none. Items of one sender sit 8px apart; any other neighbour, and either side of a system line, is 24px. The list appends a spacing class to each item after the first; the first has none.

Exports

MessageList, MessageListItemKind, MessageListSenderGap, and the types MessageListProps, MessageListItem, MessageListMessageItem, MessageListSystemItem, MessageListBlockItem, MessageListMessageProps, MessageListSystemProps and MessageListBlockProps.

Props

Name	Type	Default	Description
`emptyTitle`	`LocalizedMessage`	—	Title of the empty state, shown when there are no items and nothing is loading.
`items`	`readonly MessageListItem[]`	—	The transcript, oldest first. A list with no items shows the empty state.
`jumpToLatestLabel`	`LocalizedMessage`	—	Accessible name of the jump-to-latest control when {@link ChatScrollLayoutProps.unreadCount} is zero. When the count is above zero, {@link ChatScrollLayoutProps.jumpUnreadLabel} names the control instead.
`label`	`LocalizedMessage`	—	Accessible name of the transcript. The log element is named by it.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`emptyDescription`	`LocalizedMessage \| DisplayValue`	—	Description of the empty state.
`emptyIcon`	`Glyph`	—	Glyph in the empty state's icon well. Decorative.
`errorRow`	`ReactNode`	—	Row shown at the top of the transcript when loading older messages failed. Pauses `onReachStart` like `loadingRow`.
`jumpUnreadLabel`	`((count: number) => LocalizedMessage)`	—	Accessible name when {@link ChatScrollLayoutProps.unreadCount} is above zero. Receives the count so copy can pluralize or format the number; the count is not shown visually.
`loading`	`boolean`	—	Older messages are not loading. Shows placeholder lines at the top of the transcript and pauses `onReachStart`. Remove it in the same update that adds the older messages. A list with no items yet shows the placeholders instead of the empty state.
`loadingLabel`	`LocalizedMessage`	—	Not allowed unless `loading` is true. Announced once when loading starts, such as "Loading earlier messages". The placeholders are decorative.
`locale`	`string`	—	BCP 47 locale for formatting numbers in `jumpUnreadLabel` at the call site. ChatScroll does not read this prop; it remains for callers who format the unread count in their label callback.
`metaPlacement`	`MessageMetaPlacement`	—	Where a message's time and metadata sit in its author line. A message can set its own. Defaults to after the name.
`onAtEndChange`	`((atEnd: boolean, details: ChangeDetails<ChangeReason.None>) => void)`	—	Called when the reader moves to the latest message or away from it, once per change after mount. The transcript starts at the latest message. @param atEnd - True when the scroll offset is within a few pixels of the latest message @param details - Change metadata; the change cannot be canceled
`onReachStart`	`(() => void)`	—	Called when the start of the transcript, where the oldest loaded message is, scrolls into view. Paused while `loadingRow` or `errorRow` renders, and reported again when the row is removed if the start is still visible.
`overlay`	`ReactNode`	—	Content that floats over the block end of the transcript, such as a composer. ChatScroll measures it, keeps that much room below the last message, and lifts the jump control above it. It fades into the surface above it, and only the slot itself takes pointer events. It is outside the log, so it is not announced as transcript.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the log element, which is the scroll root.
`selfVariant`	`MessageVariant`	—	How the transcript owner's own messages (`Self`, or a `user` role) are drawn, when they differ from the rest: a bubble for the reader's messages over plain lines for the others, for example. Defaults to `variant`.
`showAuthor`	`boolean`	—	Whether messages draw the avatar and author line. Defaults to true. A message can set its own `showAuthor`. Hidden, the name stays for assistive technology and the time becomes a caption.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`unreadCount`	`number`	—	How many messages arrived while the reader was away from the latest one. The caller owns the number; it is folded into the jump control's accessible name through `jumpUnreadLabel` when above zero. Reset it from {@link ChatScrollLayoutProps.onAtEndChange}.
`variant`	`MessageVariant`	—	How the messages are drawn. Defaults to the plain transcript line; a bubble is the alternative.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Message List / Usage

Message List / Accessibility

On this page

Message List

API and Development

View SourceOpens in a new tab Submit IssueOpens in a new tab

Renders a ChatScroll log. Props are ChatScroll's, except children and loadingRow, plus the ones below.

Prop	Type	Default	Notes
`items`	`readonly MessageListItem[]`	required	The transcript, oldest first
`variant`	`MessageVariant`	`Plain`	For every message, unless `selfVariant` says otherwise
`selfVariant`	`MessageVariant`	`variant`	For the reader's own messages (`Self`, or a `user` role)
`showAuthor`	`boolean`	`true`	Avatar and author line on every message. A message's own `showAuthor` wins
`metaPlacement`	`MessageMetaPlacement`	`Inline`	Where a message's time and metadata sit in its author line. A message's own wins
`emptyIcon`	`Glyph`		Glyph in the empty state's icon well
`emptyTitle`	`LocalizedMessage`	required	Empty state title
`emptyDescription`	`LocalizedMessage \| DisplayValue`		Empty state description
`loading`	`boolean`	`false`	Placeholder lines at the top; with `loadingLabel`
`loadingLabel`	`LocalizedMessage`	required with `loading`	Announced once when loading starts

Items

Exports

Props

Name	Type	Default	Description
`emptyTitle`	`LocalizedMessage`	—	Title of the empty state, shown when there are no items and nothing is loading.
`items`	`readonly MessageListItem[]`	—	The transcript, oldest first. A list with no items shows the empty state.
`jumpToLatestLabel`	`LocalizedMessage`	—	Accessible name of the jump-to-latest control when {@link ChatScrollLayoutProps.unreadCount} is zero. When the count is above zero, {@link ChatScrollLayoutProps.jumpUnreadLabel} names the control instead.
`label`	`LocalizedMessage`	—	Accessible name of the transcript. The log element is named by it.
`aria-description`	`LocalizedMessage`	—	Extended description for assistive tech.
`aria-placeholder`	`LocalizedMessage`	—	Hint for an empty control.
`emptyDescription`	`LocalizedMessage \| DisplayValue`	—	Description of the empty state.
`emptyIcon`	`Glyph`	—	Glyph in the empty state's icon well. Decorative.
`errorRow`	`ReactNode`	—	Row shown at the top of the transcript when loading older messages failed. Pauses `onReachStart` like `loadingRow`.
`jumpUnreadLabel`	`((count: number) => LocalizedMessage)`	—	Accessible name when {@link ChatScrollLayoutProps.unreadCount} is above zero. Receives the count so copy can pluralize or format the number; the count is not shown visually.
`loading`	`boolean`	—	Older messages are not loading. Shows placeholder lines at the top of the transcript and pauses `onReachStart`. Remove it in the same update that adds the older messages. A list with no items yet shows the placeholders instead of the empty state.
`loadingLabel`	`LocalizedMessage`	—	Not allowed unless `loading` is true. Announced once when loading starts, such as "Loading earlier messages". The placeholders are decorative.
`locale`	`string`	—	BCP 47 locale for formatting numbers in `jumpUnreadLabel` at the call site. ChatScroll does not read this prop; it remains for callers who format the unread count in their label callback.
`metaPlacement`	`MessageMetaPlacement`	—	Where a message's time and metadata sit in its author line. A message can set its own. Defaults to after the name.
`onAtEndChange`	`((atEnd: boolean, details: ChangeDetails<ChangeReason.None>) => void)`	—	Called when the reader moves to the latest message or away from it, once per change after mount. The transcript starts at the latest message. @param atEnd - True when the scroll offset is within a few pixels of the latest message @param details - Change metadata; the change cannot be canceled
`onReachStart`	`(() => void)`	—	Called when the start of the transcript, where the oldest loaded message is, scrolls into view. Paused while `loadingRow` or `errorRow` renders, and reported again when the row is removed if the start is still visible.
`overlay`	`ReactNode`	—	Content that floats over the block end of the transcript, such as a composer. ChatScroll measures it, keeps that much room below the last message, and lifts the jump control above it. It fades into the surface above it, and only the slot itself takes pointer events. It is outside the log, so it is not announced as transcript.
`ref`	`Ref<HTMLDivElement>`	—	Ref to the log element, which is the scroll root.
`selfVariant`	`MessageVariant`	—	How the transcript owner's own messages (`Self`, or a `user` role) are drawn, when they differ from the rest: a bubble for the reader's messages over plain lines for the others, for example. Defaults to `variant`.
`showAuthor`	`boolean`	—	Whether messages draw the avatar and author line. Defaults to true. A message can set its own `showAuthor`. Hidden, the name stays for assistive technology and the time becomes a caption.
`title`	`LocalizedMessage`	—	Native tooltip; accessibility hint, not visible UI title text.
`unreadCount`	`number`	—	How many messages arrived while the reader was away from the latest one. The caller owns the number; it is folded into the jump control's accessible name through `jumpUnreadLabel` when above zero. Reset it from {@link ChatScrollLayoutProps.onAtEndChange}.
`variant`	`MessageVariant`	—	How the messages are drawn. Defaults to the plain transcript line; a bubble is the alternative.

Storybook

Interactive examples and edge cases for this component are in Storybook.

DefaultOpens in a new tab

Message List / Usage

Message List / Accessibility

On this page