Virtuoso Message List Item Keys

Item Keys

React uses a unique key to identify each item in a list. By default, the Message List component uses the item’s numeric index for that, but this index might change as we load new messages or delete some. To address that, the message list exposes a computeItemKey prop. This prop should return a unique key for each item based on the item data.

import { VirtuosoMessageList, VirtuosoMessageListLicense } from '@virtuoso.dev/message-list'

export default function App() {
  return (
    <VirtuosoMessageListLicense licenseKey="">
      <VirtuosoMessageList
        computeItemKey={({ data }) => {
          return `item-${data}`
        }}
        style={{ height: '100%' }}
        data={{ data: Array.from({ length: 100 }, (_, index) => index) }}
      />
    </VirtuosoMessageListLicense>
  )
}

computeItemKey And itemIdentity

computeItemKey controls the React key used to mount and update item components. Use it for every chat integration with stable message ids, local optimistic ids, or both.

itemIdentity is different. It controls how the message list matches items for controlled data operations such as prepend and remove-from-start when your reducer recreates item objects. If your controlled state creates new object references for the same messages, provide itemIdentity with the same stable identity you use for keys.

<VirtuosoMessageList
  computeItemKey={({ data }) => data.id ?? `local-${data.localId}`}
  itemIdentity={(item) => item.id ?? `local-${item.localId}`}
/>

If your data objects keep stable references across updates, itemIdentity is usually not necessary. If controlled prepend or trimming loses the previous visual position after recreating message objects, add it.