Skip to main content

Chat list

Most apps are a list of chats plus the chats themselves. ChatList is the list: map your backend's conversations to ChatListItem and wire the callbacks, and you get a messenger's main screen:

  • a header with search, and a selection bar (pin, mute, archive, delete) after a long-press
  • an "Archived Chats" folder, and swipe to archive
  • pinned chats first, which you drag into a new order (with reorder handles while selecting)
  • unread counters, typing and drafts, a loading placeholder and a new-chat button
import { Chat, ChatList, ChatListItem } from '@kesha-antonov/react-native-chat'

const chats: ChatListItem[] = conversations.map(c => ({
id: c.id,
title: c.name,
avatar: c.photoUrl,
kind: c.isGroup ? 'group' : 'private',
lastMessage: c.lastMessage, // an IMessage: preview, time and your sent/read checks
unreadCount: c.unread,
isPinned: c.pinned, // pinned chats show first, in the order you pass them
isMuted: c.muted,
isArchived: c.archived,
isOnline: c.online, // green dot on the avatar
isVerified: c.verified, // check badge after the name
typingUsers: c.typing, // User[]
typingAction: c.action, // 'typing' | 'recordingVoice' | 'sendingPhoto' | ...
draft: drafts[c.id],
}))

<ChatList
chats={chats}
user={me}
isLoading={!loaded}
onPressChat={chat => navigation.navigate('Chat', { id: chat.id })}
onPressNewChat={() => navigation.navigate('NewChat')}
onPinChats={(selected, isPinned) => api.pin(selected.map(c => c.id), isPinned)}
onMuteChats={(selected, isMuted) => api.mute(selected.map(c => c.id), isMuted)}
onArchiveChats={(selected, isArchived) => api.archive(selected.map(c => c.id), isArchived)}
onDeleteChats={selected => api.delete(selected.map(c => c.id))}
onReorderPinnedChats={ids => api.setPinnedOrder(ids)}
/>

Each action appears only when its callback is passed. The list is controlled: update chats from your backend and it follows. For a prototype, useChatList keeps the chats in local state and returns the handlers:

const list = useChatList(initialChats)
<ChatList chats={list.chats} user={me} {...list.handlers} onPressChat={openChat} />
// later: list.receiveMessage(chatId, message), list.markRead(chatId), list.upsertChat(chat)
PropWhat it does
chatsEvery chat, archived ones included
userYou: "You:" in groups and the checks on your own last messages
onPressChat / onLongPressChatA tap; a long-press (default: select)
onPinChats / onMuteChats / onArchiveChats / onDeleteChatsSelection actions; archive also by swiping a row
onReorderPinnedChatsTurns on dragging pinned chats; receives the new order of ids
onPressNewChatShows the new-chat button
isLoadingThe loading placeholder
isSortEnabledPinned first, then by newest message (default true)
isDeleteConfirmed / isSwipeEnabledAsk before deleting; swipe to archive (both default true)
isHeaderVisible / title / renderHeaderRight / isTopInsetAppliedThe built-in header (hide it to use your navigator's)
headerRightPositionrenderHeaderRight before the search button (default) or 'afterSearch', e.g. for a close button
timeFormat / dateFormatdayjs formats for a row's time today ('HH:mm' for a 24-hour clock) and its date before this week ('DD.MM.YY')
isSearchEnabled / filterChat / onSearchChangeSearch; a custom match; a server-side search
isArchiveOpen / onArchiveOpenChangeControl which list shows
renderChat / renderEmpty / listProps / styleA custom row (ChatListCell is the built-in one), the empty text, FlatList props (onEndReached, refreshControl...)
appearance / theme / darkTheme / colorScheme / locale / labels / iconsAs on Chat (pass the same appearance to Chat, ChatList and ChatHeader); the list's colors are theme.chatList

ChatListCell, ChatListAvatar, ChatListShimmer, sortChats, getChatPreview and formatChatListDate are exported for building your own row or screen.

ChatHeader is the chat screen's bar to match: back arrow, a 42 avatar, the name with a status line under it ("online" and "typing" in the accent color) and your buttons at the end, in theme.chatList's header colors.

<ChatHeader
title='Anna Petrova'
subtitle={isOnline ? 'online' : 'last seen recently'}
isSubtitleActive={isOnline}
typingUsers={typingUsers}
avatar={{ id: chat.id, uri: chat.avatar }}
onBack={navigation.goBack}
onPressTitle={openProfile}
renderRight={() => <CallButton />}
/>