@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".

PeerUsed for
react-native-svgEvery icon.
react-native-markdown-displayMarkdown in message bodies. It is imported even when you pass markdown={false}.
react-native-safe-area-contextBottom inset of the composer and the keyboard offset in PoolseInbox.
expo-clipboardThe Copy action.
expo-image-pickerCamera and photo library in AttachmentPicker.
expo-document-pickerFiles in AttachmentPicker.
expo-image-manipulatorResizes 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 inactive state (notification centre, app switcher) doesn't pause anything.
  • After the reconnect, useMessages and useConversations reload from REST to pick up what was sent while the app was away (see Reconnects). ConversationView also 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.

PropTypeDefaultMeaning
titlestring'Chats'
usersInboxUser[]—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.
emptyStateReactNode | string—
keyboardOffsetnumbercomputedOverride 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.

PropTypeDefaultMeaning
conversationIdstringrequired
emptyStateReactElement | string—
renderMessage(msg, currentUserId) => ReactElement | null | undefined—Replace each row.
labelFor(externalId) => string—
avatarFor(externalId) => string | null—
headerboolean | ReactElementtruetrue: 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.
reactionsbooleantrue
mentionsbooleantrue
attachmentsbooleantrue
actionsbooleantrueLong-press menu.
threadsbooleantrue
quotationsbooleantrueIncludes swipe-to-reply on a message.
readReceiptsbooleantrue
markdownbooleantrueBare URLs become links.
maxBodyLengthnumber200"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.
keyboardOffsetnumber—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.
currentCallIdstring | 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>

PropTypeMeaning
conversationIdstringRequired.
labelFor / avatarForresolvers
onBack() => voidShows a back button.
onPress() => voidTap on the title.
onMembersPress() => voidShows 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.

PropTypeMeaning
visiblebooleanRequired.
onClose() => voidRequired.
conversationIdstringRequired.
rootMessageMessageRequired.
labelFor / avatarForresolvers

<GroupDetailsSheet>

PropTypeMeaning
visiblebooleanRequired.
onClose() => voidRequired.
conversationIdstringRequired.
labelFor / avatarForresolvers
canRemoveMember(m: { user_id; external_id; role }) => booleanShows 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.

PropTypeMeaning
messagesMessage[]Required. Oldest first.
renderItem(msg, index) => ReactElementRequired.
itemsMessageListItem[]Optional pre-built list with separators: { kind: 'msg'; msg } or { kind: 'separator'; id; node }.
loadingboolean
hasMoreboolean
onLoadMore() => void
ListHeaderReactElement | nullShown next to the newest message (for example the typing indicator).
ListFooterReactElement | nullShown past the oldest message.
emptyStateReactElement | string
meIdstring | nullPoolse 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.

PropTypeMeaning
msgMessageRequired.
meIdstring | nullRequired. Poolse user id.
reactions, attachments, actions, threads, quotations, markdownbooleanFeature switches.
readState'sent' | 'read'
isEditingboolean
onStartEdit, onDelete, onOpenThread, onQuote() => voidActions.
labelFor / avatarForresolvers
onQuotedClick(quotedMessageId) => void
groupPosition'standalone' | 'first' | 'middle' | 'last'
maxBodyLengthnumber
showSenderName / showAvatarboolean
onCallBack(media) => voidFor call-log rows.

<MessageBubble>

PropTypeMeaning
messageMessageRequired.
currentUserIdstring | nullRequired. Poolse user id.
readState'sent' | 'read'
labelFor(externalId) => string
onQuotedClick(quotedMessageId) => void
groupPosition'standalone' | 'first' | 'middle' | 'last'
maxBodyLengthnumber
showSenderNameboolean
actionsTriggerReactNode
onLongPress() => void
showAttachmentsboolean
markdownboolean

There is no EditableMessageBubble in this package; editing happens in MessageComposer (editingMessage).

<MessageComposer>

PropTypeMeaning
onSend(body, opts?: { quoted_message_id?; attachment_ids? }) => Promise<unknown> | voidRequired.
onTyping() => void
placeholderstring
disabledboolean
replyingToMessage | nullThe quoted message.
onCancelReply() => void
labelFor(externalId) => string
attachmentsbooleanShow the attach button.
onAttachPress() => voidCalled by the attach button (open AttachmentPicker).
keyboardOffsetnumber
editingMessageMessage | nullPuts 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.

PropTypeMeaning
visiblebooleanRequired.
onClose() => voidRequired.
isSelfbooleanRequired. Edit and delete only show for your own messages.
emojisstring[]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.

PropTypeDefaultMeaning
visiblebooleanrequired
onClose() => voidrequired
camerabooleantrueShow the Camera item. Turn it off if your app doesn't ask for camera access.
onPickInputs(kind: 'image' | 'document' | 'camera') => Promise<AttachmentUploadInput[]>built inReplace 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>

PropTypeMeaning
attachmentAttachmentRequired.
onPress() => void
maxWidthnumber
tone'default' | 'onBrand'onBrand for use on your own (brand-coloured) bubble.

<ImageMosaic>

The image grid used inside bubbles.

PropTypeMeaning
imagesAttachment[]Required.
maxWidthnumber
radiusnumber
squareBottombooleanSquare 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

ComponentProps
Avatarsrc, name, seed (a stable string for the fallback colour), online, size ('sm' | 'md' | 'lg')
PoolseIconname (IconName, required), size (number), color, label
PoolseLogovariant ('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.

PropTypeMeaning
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.
themePoolseRNThemeOverridesPartial overrides, merged over the base one group at a time.
childrenReactNode
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>

PropTypeDefaultMeaning
iconIconNamerequired
onPress() => voidrequired
labelstring—Text under the button.
activebooleanfalseEngaged (for example muted): drawn solid white.
tone'neutral' | 'danger' | 'accept''neutral'danger for hang up, accept for answer.
largebooleanfalse68 pt instead of 58 pt.
disabledbooleanfalse
accessibilityLabelstring—

<CallAvatar>

A round avatar with initials and a ring that shows while the person speaks (the avatar itself doesn't resize).

PropTypeMeaning
namestringRequired. Initials come from it.
seedstringRequired. Picks a stable colour.
sizenumberRequired. Diameter in points.
speakingbooleanShows the ring.

<AudioRouteSheet>

A sheet for choosing where call audio plays.

PropTypeMeaning
visiblebooleanRequired.
routesAudioRoute[]Required. { id, kind, label }, with kind one of 'speaker' | 'earpiece' | 'headset' | 'bluetooth' | 'auto' (AudioRouteKind).
selectedRouteIdstring | nullRequired.
onSelect(id: string) => voidRequired.
onClose() => voidRequired.

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)
StylingCSS variables<PoolseTheme> object
Dark modefollows the system, or data-thememode prop
Message actionshover menulong press, as a sheet
Reaction and mention pickerspopoverssheets
Quotefrom the menualso swipe right on a message
Threadside panebottom sheet
Attachmentsfile input, drag and dropAttachmentPicker (camera, photos, files)
Markdownreact-markdown + GFMreact-native-markdown-display, bare URLs linked
Room UI (RoomStage, RoomJoinBar)yesno; 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.

@poolse/react-native · poolse docs