@poolse/react-native
Prebuilt chat components for React Native and Expo, built on the
@poolse/react hooks. The component names follow
@poolse/react-ui, but the props differ where the
platforms differ; each component's props are listed below.
Calls on phones (ringing a locked phone, CallKit, the Android call service)
live in @poolse/native. This package has the pieces for
drawing a call screen.
Install
npx expo install \
@poolse/sdk @poolse/react @poolse/react-native \
react-native-svg \
react-native-markdown-display \
react-native-safe-area-context \
expo-clipboard \
expo-image-picker \
expo-document-picker \
expo-image-manipulator
npx expo install picks versions that match your Expo SDK. Without the Expo
CLI, use npm install and choose versions yourself. Declared peer ranges:
react ≥ 18, react-native ≥ 0.73, react-native-svg ≥ 14,
react-native-safe-area-context ≥ 4, react-native-markdown-display ≥ 7;
the expo-* peers accept any version.
Every peer is required. The package imports each of them when it loads, so a missing one fails the bundle with "Unable to resolve module".
| Peer | Used for |
|---|---|
react-native-svg | Every icon. |
react-native-markdown-display | Markdown in message bodies. It is imported even when you pass markdown={false}. |
react-native-safe-area-context | Bottom inset of the composer and the keyboard offset in PoolseInbox. |
expo-clipboard | The Copy action. |
expo-image-picker | Camera and photo library in AttachmentPicker. |
expo-document-picker | Files in AttachmentPicker. |
expo-image-manipulator | Resizes picked photos and converts them to WebP before upload. |
iOS needs usage strings for the picker (app.json → ios.infoPlist):
{
"NSCameraUsageDescription": "Take photos to send in chat.",
"NSPhotoLibraryUsageDescription": "Pick photos to send in chat."
}
Wrap your app in SafeAreaProvider from react-native-safe-area-context.
Quick start: an inbox
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
import { PoolseProvider } from '@poolse/react';
import { PoolseInbox, PoolseTheme, useAppStateLifecycle } from '@poolse/react-native';
import type { InboxUser } from '@poolse/react-native';
const users: InboxUser[] = [
{ externalId: 'alice', name: 'Alice', avatarUrl: null },
{ externalId: 'bob', name: 'Bob', avatarUrl: null },
];
export default function App() {
return (
<SafeAreaProvider>
<PoolseProvider config={config /* see @poolse/react */}>
<ChatRoot />
</PoolseProvider>
</SafeAreaProvider>
);
}
function ChatRoot() {
useAppStateLifecycle(); // must be inside PoolseProvider
return (
<SafeAreaView style={{ flex: 1 }}>
<PoolseTheme>
<PoolseInbox
title="Chats"
users={users}
labelFor={(id) => users.find((u) => u.externalId === id)?.name ?? id}
avatarFor={(id) => users.find((u) => u.externalId === id)?.avatarUrl ?? null}
/>
</PoolseTheme>
</SafeAreaView>
);
}
Quick start: one conversation
import { PoolseTheme, ConversationView } from '@poolse/react-native';
export function ChatScreen({ conversationId }: { conversationId: string }) {
return (
<PoolseTheme>
<ConversationView conversationId={conversationId} keyboardOffset={headerHeight} />
</PoolseTheme>
);
}
Mount it under the same PoolseProvider. PoolseTheme is optional; without
it the light theme is used. When you mount ConversationView yourself, pass
keyboardOffset on iOS: the distance from the top of the screen to the top
of the view (status bar, safe area and any navigation header).
useAppStateLifecycle()
Call it once, in a component inside <PoolseProvider>. Calling it
above the provider throws.
From 3.1:
- When the app goes to the background, it calls
poolse.realtime.pause(): the socket closes, but every channel and listener is kept. - When the app becomes active again, it calls
resume(): the socket reopens with a current token and the channels rejoin. Mounted hooks keep receiving events. - The iOS
inactivestate (notification centre, app switcher) doesn't pause anything. - After the reconnect,
useMessagesanduseConversationsreload from REST to pick up what was sent while the app was away (see Reconnects).ConversationViewalso reloads its messages whenever the app becomes active.
While the socket is paused, poolse's push notifications are how the user
hears about new messages and calls. Those need
@poolse/native and registered devices; see
Push notifications.
In 3.0 this hook called realtime.disconnect() on any state other than
active, which destroyed every channel; mounted hooks then stopped getting
events until they remounted. Upgrade to 3.1.
<PoolseInbox>
A conversation list and the open conversation. Opening a conversation slides
it in; swiping from the left edge (or the back button) returns to the list.
With users, the header shows New chat and New group, which open pickers.
| Prop | Type | Default | Meaning |
|---|---|---|---|
title | string | 'Chats' | |
users | InboxUser[] | — | Your user directory for the pickers. |
labelFor | (externalId) => string | — | |
avatarFor | (externalId) => string | null | — | |
renderRightAction | () => ReactNode | — | Extra content in the list header. |
renderConversationRow | (conv, callerExternalId, selected) => ReactNode | — | Replace each row. |
emptyState | ReactNode | string | — | |
keyboardOffset | number | computed | Override the keyboard offset it passes to the conversation. |
InboxUser is { externalId: string; name: string; subtitle?: string; avatarUrl?: string | null }.
A ref gives a PoolseInboxHandle with open(conversationId),
openDirect(externalId) and openGroup(name, memberExternalIds) (both
return promises), promptNewChat(), promptNewGroup() and close(), as on
the web.
<ConversationView>
One conversation: header, message list, composer, typing indicator,
attachments, reactions, quotes and a thread sheet, inside one
KeyboardAvoidingView.
| Prop | Type | Default | Meaning |
|---|---|---|---|
conversationId | string | required | |
emptyState | ReactElement | string | — | |
renderMessage | (msg, currentUserId) => ReactElement | null | undefined | — | Replace each row. |
labelFor | (externalId) => string | — | |
avatarFor | (externalId) => string | null | — | |
header | boolean | ReactElement | true | true: the built-in ChatHeader. false: none. An element: yours. |
onHeaderPress | () => void | — | Tap on the header title. |
onHeaderMembersPress | () => void | — | Shows a members button in the header. |
reactions | boolean | true | |
mentions | boolean | true | |
attachments | boolean | true | |
actions | boolean | true | Long-press menu. |
threads | boolean | true | |
quotations | boolean | true | Includes swipe-to-reply on a message. |
readReceipts | boolean | true | |
markdown | boolean | true | Bare URLs become links. |
maxBodyLength | number | 200 | "Read more" threshold. |
senderLabels | 'auto' | 'always' | 'never' | 'auto' | auto: more than two members. |
avatars | 'auto' | 'always' | 'never' | 'auto' | Same rule. |
onMarkedRead | (conversationId, messageId) => void | — | After the view advances your read cursor. |
onSent | (conversationId) => void | — | After a message is sent, for example to refetch() a list elsewhere. |
keyboardOffset | number | — | iOS keyboard offset. PoolseInbox sets it for you. |
onCallBack | (media) => void | — | "Call back" on call-log rows. |
onJoinCall | (call: LiveCall) => void | — | Shows a Join banner while a call or room is live and you aren't in it. |
currentCallId | string | null | — | The call you are on; its banner is hidden. |
Unlike the web view, there are no grouping, daySeparators,
groupingWindowMs or loadFonts props: grouping (5-minute window) and day
separators are always on, and fonts are your app's.
The view reloads its newest messages when the app becomes active and when the socket reconnects.
Components
<ChatHeader>
| Prop | Type | Meaning |
|---|---|---|
conversationId | string | Required. |
labelFor / avatarFor | resolvers | |
onBack | () => void | Shows a back button. |
onPress | () => void | Tap on the title. |
onMembersPress | () => void | Shows a members button. |
<ThreadView>
A bottom sheet with a thread's replies and its own composer. Drag the header down, tap the backdrop or the close button to dismiss.
| Prop | Type | Meaning |
|---|---|---|
visible | boolean | Required. |
onClose | () => void | Required. |
conversationId | string | Required. |
rootMessage | Message | Required. |
labelFor / avatarFor | resolvers |
<GroupDetailsSheet>
| Prop | Type | Meaning |
|---|---|---|
visible | boolean | Required. |
onClose | () => void | Required. |
conversationId | string | Required. |
labelFor / avatarFor | resolvers | |
canRemoveMember | (m: { user_id; external_id; role }) => boolean | Shows a remove action where it returns true. |
<MessageList>
An inverted FlatList that calls onLoadMore as you scroll towards the
oldest message while hasMore is true.
| Prop | Type | Meaning |
|---|---|---|
messages | Message[] | Required. Oldest first. |
renderItem | (msg, index) => ReactElement | Required. |
items | MessageListItem[] | Optional pre-built list with separators: { kind: 'msg'; msg } or { kind: 'separator'; id; node }. |
loading | boolean | |
hasMore | boolean | |
onLoadMore | () => void | |
ListHeader | ReactElement | null | Shown next to the newest message (for example the typing indicator). |
ListFooter | ReactElement | null | Shown past the oldest message. |
emptyState | ReactElement | string | |
meId | string | null | Poolse user id. With it, a "↓ N new messages" button appears when others post while you are scrolled up. |
<MessageRow>
One message with its bubble, avatar, reactions, thread pill, swipe-to-reply and long-press menu.
| Prop | Type | Meaning |
|---|---|---|
msg | Message | Required. |
meId | string | null | Required. Poolse user id. |
reactions, attachments, actions, threads, quotations, markdown | boolean | Feature switches. |
readState | 'sent' | 'read' | |
isEditing | boolean | |
onStartEdit, onDelete, onOpenThread, onQuote | () => void | Actions. |
labelFor / avatarFor | resolvers | |
onQuotedClick | (quotedMessageId) => void | |
groupPosition | 'standalone' | 'first' | 'middle' | 'last' | |
maxBodyLength | number | |
showSenderName / showAvatar | boolean | |
onCallBack | (media) => void | For call-log rows. |
<MessageBubble>
| Prop | Type | Meaning |
|---|---|---|
message | Message | Required. |
currentUserId | string | null | Required. Poolse user id. |
readState | 'sent' | 'read' | |
labelFor | (externalId) => string | |
onQuotedClick | (quotedMessageId) => void | |
groupPosition | 'standalone' | 'first' | 'middle' | 'last' | |
maxBodyLength | number | |
showSenderName | boolean | |
actionsTrigger | ReactNode | |
onLongPress | () => void | |
showAttachments | boolean | |
markdown | boolean |
There is no EditableMessageBubble in this package; editing happens in
MessageComposer (editingMessage).
<MessageComposer>
| Prop | Type | Meaning |
|---|---|---|
onSend | (body, opts?: { quoted_message_id?; attachment_ids? }) => Promise<unknown> | void | Required. |
onTyping | () => void | |
placeholder | string | |
disabled | boolean | |
replyingTo | Message | null | The quoted message. |
onCancelReply | () => void | |
labelFor | (externalId) => string | |
attachments | boolean | Show the attach button. |
onAttachPress | () => void | Called by the attach button (open AttachmentPicker). |
keyboardOffset | number | |
editingMessage | Message | null | Puts the composer in edit mode for that message. |
onCancelEdit | () => void | |
onSaveEdit | (body: string) => Promise<unknown> | void |
<MentionInput>
Every MessageComposer prop, plus conversationId (required), with @
autocomplete over the members. Its onSend receives
(body, opts?: { quoted_message_id?; attachment_ids?; mentions? }).
<MessageActions>
The long-press menu as a sheet.
| Prop | Type | Meaning |
|---|---|---|
visible | boolean | Required. |
onClose | () => void | Required. |
isSelf | boolean | Required. Edit and delete only show for your own messages. |
emojis | string[] | Quick reactions. |
onPickReaction | (emoji) => void | |
onReply, onReplyInThread, onQuote, onEdit, onDelete, onCopy | () => void |
<TypingIndicator>
typing: Set<string> (external ids, required) and labelFor.
<DaySeparator>
label: string. A centred day label; use it with formatDayLabel from
@poolse/react.
<ConversationList>
A FlatList of conversations. Same props as the
web ConversationList:
selectedId, onSelect, renderItem, emptyState (ReactNode | string),
conversations, loading, error, unreadCounts, labelFor,
avatarFor.
<MemberList>
Same props as the web MemberList:
conversationId, labelFor, avatarFor, onlineExternalIds,
canRemove, renderItem, emptyState (ReactNode | string).
<ReactionStrip> and <ReactionPicker>
ReactionStrip: messageId, conversationId, meId (poolse user id,
required) and initialReactions.
ReactionPicker is a sheet: visible, onClose, onPick(emoji) (all
required) and emojis (the choices).
<AttachmentPicker>
A sheet with Camera, Photo and File. Picked items go into the upload queue.
Inside ConversationView that queue is the composer's, so the next send
includes them.
| Prop | Type | Default | Meaning |
|---|---|---|---|
visible | boolean | required | |
onClose | () => void | required | |
camera | boolean | true | Show the Camera item. Turn it off if your app doesn't ask for camera access. |
onPickInputs | (kind: 'image' | 'document' | 'camera') => Promise<AttachmentUploadInput[]> | built in | Replace the default pickers. |
Photos from the default picker are resized and saved as WebP. From 3.1 the
default picker declares the size of the bytes it actually uploads, which
the server requires (a file bigger than its declared size can't be sent).
A custom onPickInputs must do the same: set byteSize to the size of
body.
<UploadQueueStrip>
No props. Shows the uploads of the surrounding ConversationView or
ThreadView, with cancel. Outside those it has its own empty queue, so it
is only useful inside them.
<AttachmentPreview>
| Prop | Type | Meaning |
|---|---|---|
attachment | Attachment | Required. |
onPress | () => void | |
maxWidth | number | |
tone | 'default' | 'onBrand' | onBrand for use on your own (brand-coloured) bubble. |
<ImageMosaic>
The image grid used inside bubbles.
| Prop | Type | Meaning |
|---|---|---|
images | Attachment[] | Required. |
maxWidth | number | |
radius | number | |
squareBottom | boolean | Square the bottom corners (when text follows). |
onLongPress | () => void |
<CallLogRow> and <LiveCallBanner>
Same props as on the web: CallLogRow takes msg, meId and onCallBack;
LiveCallBanner takes call, inCall and onJoin. See
@poolse/react-ui.
<UserName> and useDisplayName
<UserName externalId fallback? labelFor? />. useDisplayName(externalId)
returns the name as a string. Order: labelFor, your userResolver, then
the external id.
<Avatar>, <PoolseIcon>, <PoolseLogo> and Primitives
| Component | Props |
|---|---|
Avatar | src, name, seed (a stable string for the fallback colour), online, size ('sm' | 'md' | 'lg') |
PoolseIcon | name (IconName, required), size (number), color, label |
PoolseLogo | variant ('lockup' | 'mark' | 'wordmark' | 'mono'), size, color, label |
Primitives is an object holding the same three: { PoolseIcon, PoolseLogo, Avatar }.
Theming
<PoolseTheme> puts a theme in context; every component reads it.
| Prop | Type | Meaning |
|---|---|---|
mode | 'light' | 'dark' | Base palette. Defaults to light. It doesn't follow the system setting by itself; pass useColorScheme() from react-native if you want that. |
theme | PoolseRNThemeOverrides | Partial overrides, merged over the base one group at a time. |
children | ReactNode |
import { useColorScheme } from 'react-native';
<PoolseTheme
mode={useColorScheme() === 'dark' ? 'dark' : 'light'}
theme={{ colors: { brand: '#ff5733', brandSoft: '#ffe9e3' }, radii: { bubble: 18 } }}
>
{children}
</PoolseTheme>
usePoolseTheme() returns the active PoolseRNTheme (the light default
outside a PoolseTheme). defaultLightTheme and defaultDarkTheme are the
two base themes.
interface PoolseRNTheme {
mode: 'light' | 'dark';
colors: ThemeColors; // brand, brandStrong, brandSoft, onBrand, paper, surface, surface2,
// ink, ink2, ink3, border, presence, success, warning, error, info,
// selfBubble, selfBubbleText, otherBubble, otherBubbleText,
// unreadPill, unreadPillText (all strings)
type: ThemeType; // fontDisplay, fontBody, fontMono, bodySize, lineHeight,
// weightRegular '400', weightMedium '500', weightSemibold '600', weightBold '700'
radii: ThemeRadii; // sm, md, lg, xl, pill, bubble (numbers)
spacing: ThemeSpacing; // xs, sm, md, lg, xl (numbers)
shadows: ThemeShadows; // sm, md, lg: { shadowColor, shadowOpacity, shadowOffset, shadowRadius, elevation }
}
PoolseRNThemeOverrides has the same groups, each Partial. PoolseThemeProps,
ThemeColors, ThemeType, ThemeRadii, ThemeSpacing and ThemeShadows
are exported types.
Call-screen building blocks
@poolse/native gives you a Snapshot of the call. These help you draw it.
<CallControlButton>
| Prop | Type | Default | Meaning |
|---|---|---|---|
icon | IconName | required | |
onPress | () => void | required | |
label | string | — | Text under the button. |
active | boolean | false | Engaged (for example muted): drawn solid white. |
tone | 'neutral' | 'danger' | 'accept' | 'neutral' | danger for hang up, accept for answer. |
large | boolean | false | 68 pt instead of 58 pt. |
disabled | boolean | false | |
accessibilityLabel | string | — |
<CallAvatar>
A round avatar with initials and a ring that shows while the person speaks (the avatar itself doesn't resize).
| Prop | Type | Meaning |
|---|---|---|
name | string | Required. Initials come from it. |
seed | string | Required. Picks a stable colour. |
size | number | Required. Diameter in points. |
speaking | boolean | Shows the ring. |
<AudioRouteSheet>
A sheet for choosing where call audio plays.
| Prop | Type | Meaning |
|---|---|---|
visible | boolean | Required. |
routes | AudioRoute[] | Required. { id, kind, label }, with kind one of 'speaker' | 'earpiece' | 'headset' | 'bluetooth' | 'auto' (AudioRouteKind). |
selectedRouteId | string | null | Required. |
onSelect | (id: string) => void | Required. |
onClose | () => void | Required. |
With @poolse/native, build the routes from snapshot.audioOutputs and
call setAudioOutput(id) in onSelect.
callColors
The call screen's dark palette (calls stay dark whatever the app theme):
bg, glow, glowWarm, glass, glassBorder, tile, scrim, text,
textDim, textFaint, control, controlActive, controlActiveIcon,
danger, accept, onAction.
useCallDuration(connected)
Returns the time since connected became true as m:ss (or h:mm:ss),
updated every second, or null while not connected. It measures from a
timestamp, so it stays right when timers are throttled.
const duration = useCallDuration(snapshot?.phase === 'active');
Names and ids
Props named labelFor, avatarFor, externalId, onlineExternalIds and
the typing set use your user ids. meId, currentUserId and
renderMessage's currentUserId are poolse user ids (useMe().me.id).
Differences from the web components
Web (@poolse/react-ui) | React Native (this package) | |
|---|---|---|
| Styling | CSS variables | <PoolseTheme> object |
| Dark mode | follows the system, or data-theme | mode prop |
| Message actions | hover menu | long press, as a sheet |
| Reaction and mention pickers | popovers | sheets |
| Quote | from the menu | also swipe right on a message |
| Thread | side pane | bottom sheet |
| Attachments | file input, drag and drop | AttachmentPicker (camera, photos, files) |
| Markdown | react-markdown + GFM | react-native-markdown-display, bare URLs linked |
Room UI (RoomStage, RoomJoinBar) | yes | no; rooms on phones run in @poolse/native |
Exported types
PoolseInboxProps, PoolseInboxHandle, InboxUser, ConversationViewProps,
ChatHeaderProps, GroupDetailsSheetProps, MessageBubbleProps,
MessageRowProps, CallLogRowProps, LiveCallBannerProps,
MessageComposerProps, MessageActionsProps, MessageListProps,
MessageListItem, DaySeparatorProps, TypingIndicatorProps,
ThreadViewProps, UserNameProps, ConversationListProps,
MemberListProps, AttachmentPreviewProps, ReactionStripProps,
ReactionPickerProps, MentionInputProps, AttachmentPickerProps,
ImageMosaicProps, PoolseIconProps, IconName, PoolseLogoProps,
PoolseLogoVariant, AvatarProps, PoolseThemeProps, PoolseRNTheme,
PoolseRNThemeOverrides, ThemeColors, ThemeType, ThemeRadii,
ThemeSpacing, ThemeShadows, CallControlButtonProps, CallAvatarProps,
AudioRouteSheetProps, AudioRoute, AudioRouteKind.