Skip to content
Projects

kesha-antonov/react-native-chat has 88 GitHub stars and 12 forks. GitHot measured +1 stars in 24 hours and +6 in 7 days. Last checked 2026-11-16 21:57 UTC. Last push 2026-11-06.

How these counts are measured

What you can do

  • 💬 Chat list - the list of chats with search, selection actions, archive, swipe to archive and draggable pinned chats; plug in your backend
  • 🌗 Dark mode & theming - full light/dark token system, switchable at runtime
  • 🤖 Streaming AI messages - token-by-token replies with a typing caret and stop control
  • 😀 Emoji reactions - long-press picker and reaction pills

Measured star growth

in 24h
+1
in 7 days
+6
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

The most complete chat UI for React Native & Web - streaming AI messages, emoji reactions, replies, quick replies, and full customization. TypeScript-first, Expo-ready.

Web & Apps

README.md

Original

npm version npm downloads total npm downloads npm downloads (last 18 months) build platforms TypeScript Expo compatible

React Native Chat

The most complete chat UI for React Native & Web

Chat list, photo viewer, reactions, swipe-to-reply, emoji keyboard, photo attachments, a voice note, a streamed AI reply and swipe-to-archive

Try Chat on Expo Snack

Coming from react-native-gifted-chat? This is a drop-in replacement - same IMessage, same props, a few renamed exports.
Migrate in one command with the codemod →

📖 Documentation  ·  Installation  ·  Usage  ·  Props  ·  Guides

Using it in production? A ⭐ helps other developers find the library.


Sponsors

Stream
Stream - React Native Chat SDK


cryptoc app icon

QR code that installs cryptoc
Scan to install

Get it on Google Play

Support my work

cryptoc - my crypto portfolio app. Your coins on the home screen, lock screen and watch face. iPhone, iPad, Mac, Apple Watch, Android, Android tablet and Wear OS.

  • Portfolio with average buy price and 24h / 180-day / all-time P&L
  • Widgets in three sizes, refreshed in the background - most days you never open the app
  • Price alerts on 5,000+ coins, delivered while the app is closed
  • No account, no email, no exchange API keys, no ads. Your holdings never reach a server - they sync through your own iCloud or Google Drive
  • Free for 3 holdings, and that is not a trial timer

Downloading it is what pays for the time that goes into these libraries.


Quick start

npx expo install @kesha-antonov/react-native-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
import { useCallback, useState } from 'react'
import { Chat } from '@kesha-antonov/react-native-chat'

export function Example () {
  const [messages, setMessages] = useState([
    {
      _id: 1,
      text: 'Hello developer',
      createdAt: new Date(),
      user: { _id: 2, name: 'John Doe', avatar: 'https://placeimg.com/140/140/any' },
    },
  ])

  const onSend = useCallback((newMessages = []) => {
    setMessages(previous => Chat.append(previous, newMessages))
  }, [])

  return <Chat messages={messages} onSend={onSend} user={{ _id: 1 }} />
}

That is the whole setup - everything below is optional.


✨ Features

A chat with an assistant, opened on a big waving emoji and quick replies: a long press adds a heart reaction, a swipe quotes the message in the composer, the reply is sent and its ticks turn to read, the assistant's answer streams in word by word with a link preview, a held mic sends a voice note, a round video note is filmed and sent, a photo is picked from the attachment sheet, then the same chat switches to the dark theme. Beside it, the features list and the other built-in features

Actively maintained, New Architecture ready, built for the latest Reanimated / Gesture Handler.

Chat list with unread badges, pins, mutes and swipe-to-archive    Group chat with names, avatars, a photo, a file, a reply and reactions    The same group chat in the dark theme

Built-in emoji keyboard in place of the system keyboard    Attachment menu with the photo grid, two photos picked and a caption field    Link preview cards and an emoji-only message shown large

Chat list in the dark theme


🆕 What's new vs react-native-gifted-chat

Kept in sync with upstream react-native-gifted-chat's latest master, so you keep everything it already has - and the same IMessage model and prop names. Everything added here is non-breaking and opt-in; the media and recording features only activate once you install their optional peer deps.

Side-by-side comparison
Added in this fork react-native-gifted-chat @kesha-antonov/react-native-chat
Active maintenance 💤 sporadic ✅ active
Modern default UI (modern messenger look) dated 2020 look ✅ wallpaper, tails, inline time, fully overridable
Light/Dark theme system per-component color props ✅ theme / darkTheme tokens, runtime switch
Streaming (AI) messages ❌ ✅ token-by-token + typing cursor
Emoji reactions ❌ ✅ long-press picker + reaction pills
Emoji keyboard ❌ ✅ built in: tabs, search, recents, skin tones
Attachment menu ❌ (actions sheet) ✅ built in: photo grid + caption, files, location
File messages ❌ ✅ IMessage.file document bubble
Swipe-to-reply + reply preview ❌ ✅ built in
Video / audio messages "not implemented, render your own" ✅ inline players + tappable fallback
Voice notes (hold-to-record + waveform) ❌ ✅ optional
Video messages (round camera notes) ❌ ✅ optional
Location messages ❌ ignored ✅ map card → opens system maps
Bubble tails, inline time + run grouping flat bubbles ✅

Theming in one line

Override any token, light and dark
// Modern defaults out of the box, or override any token (light + dark):
<Chat
  theme={{ colors: { accent: '#3390EC', outgoingBubble: '#EFFEDE' } }}
  darkTheme={{ colors: { background: '#0E1621' } }}
  {...props}
/>

Voice, video and location

Recording and media playback

Voice notes (expo-audio) and round video notes (react-native-vision-camera) turn on by themselves once their peers are installed: the mic button records on hold, and a tap switches it to the camera. Pass false to turn either off.

<Chat
  videoRecording={{ maxDuration: 30 }}   // optional: configure; `false` turns round notes off
  mediaPlayback={{ playbackRate: 1.5 }}  // optional: start notes at 1.5x, auto-play the next note
  // location messages render automatically for any IMessage with a `location`
  {...props}
/>
# Optional inline media playback + recording:
npx expo install expo-video expo-audio expo-image-picker
# Optional: round video notes and the voice-note waveform
# (vision-camera 5+, which runs on Nitro and needs its two Nitro packages too)
npx expo install react-native-vision-camera react-native-nitro-modules react-native-nitro-image react-native-audio-api react-native-svg expo-haptics
# Optional: trim paused voice takes, blur behind the round-video camera
npx expo install expo-file-system expo-blur

Recording and playback work like this:

  • Hold the record button to record, release to send. With both voice and video enabled, a tap switches it between mic and camera, and the choice is remembered. With only video, the camera sits in the record button's place.
  • Slide left to cancel: all the way across cancels at once; releasing past about half the way cancels too. Slide up to lock and keep recording hands-free. The two exclude each other: no lock once the cancel slide is under way. "Slide up to lock" is shown for the first few takes.
  • Locked, the bar shows a m:ss,t timer and a CANCEL button, and the lock turns into a pause button.
  • A paused voice take turns into a preview: its waveform with play, to send or delete. The mic above send resumes recording onto its end, and the handles at either end of the waveform trim it. Resuming needs react-native-audio-api; trimming also needs expo-file-system, and a trimmed take is sent as a WAV.
  • A paused round video take holds the recording open: the circle shows the frame it paused on (Android; iOS keeps the live camera, dimmed), the bar offers delete and send, and the camera above send resumes into the same video. Round takes can't be trimmed.
  • A round note records on the first hold, with the camera drawn over a blurred chat (when expo-blur is installed). Switch camera and flash work while recording (the screen lights up for the front camera, the torch for the back one), and you can pinch to zoom. At its 60s limit the take stops into a looping preview (tap to hear it) instead of sending.
  • Haptic ticks on start, stop, lock and mode switch when expo-haptics is installed.
  • Starting a recording pauses any note that is playing.
  • Only one note plays at a time. When a voice or round video note plays to its end, the next newer one in the chat starts.
  • While a note plays or is paused, a "now playing" bar at the top of the chat has play/pause, the sender, the speed (1x / 1.5x / 2x; long-press for more, shared by every note) and close; a tap on the title scrolls to the note.
  • Round notes rest in the list on their first frame with a play button (or loop silently with isRoundVideoAutoplayEnabled). A tap plays one from the start with sound and grows it, hiding the sender's avatar; a tap pauses it, and a paused note can be scrubbed by dragging around its ring. Its length, in a pill at its bottom-left, counts down while it plays, and playing bars replace its unread dot once it is heard.
  • Set isMediaUnread on a message for the unread dot; mediaPlayback.onMediaRead reports when an incoming one is played.

Emoji keyboard and attachment menu

Built in, on by default

The composer's emoji button opens the built-in emoji keyboard in the system keyboard's place - at the last keyboard height, so switching between the two keeps the composer still. It has the category tabs, search (scroll the grid up to reveal it), recents by use count, a skin-tone popup on long-press and a repeating backspace. A tap inserts at the caret whether or not you control text.

The paperclip opens the built-in attachment menu: your newest photos in a 3-column grid (with expo-media-library), numbered as you pick them, a caption and a "Send N" button; File and Location tabs; a camera tile. Picks arrive in onSend as ordinary messages - image, video, file ({ uri, name, size?, mimeType? }) or location - so there is nothing to wire.

# Each tab shows only when its package is installed:
npx expo install expo-media-library expo-image-picker expo-document-picker expo-location
# Optional: keep emoji recents across launches, share received files, fast ph:// thumbnails
npx expo install @react-native-async-storage/async-storage expo-sharing expo-image
<Chat
  emojiKeyboard={{ columns: 8, recents: { storageKey: 'my-app/emoji' } }}
  attachments={{
    tabs: ['gallery', 'file'],
    // Upload first, then send what your backend returns (or `null` to send nothing).
    onPick: async (picked, { caption }) => upload(picked, caption),
  }}
  {...props}
/>

Hide either with emojiKeyboard={false} / attachments={false}. onPressEmoji replaces the emoji keyboard and actions / onPressActionButton / renderActions replace the attachment menu, as before.

Permissions. iOS kills an app that asks for a permission without a usage string. In Expo, list the plugins with your own strings (the defaults are generic):

"plugins": [
  ["expo-image-picker", { "photosPermission": "...", "cameraPermission": "..." }],
  ["expo-media-library", { "photosPermission": "...", "savePhotosPermission": "...", "granularPermissions": ["photo", "video"] }],
  ["expo-location", { "locationWhenInUsePermission": "..." }],
  "expo-document-picker",
  "expo-sharing"
]

In a bare app add the keys yourself, then rebuild the native app:

Package iOS Info.plist Android manifest
expo-media-library NSPhotoLibraryUsageDescription (NSPhotoLibraryAddUsageDescription to save) READ_MEDIA_IMAGES, READ_MEDIA_VIDEO (READ_EXTERNAL_STORAGE below Android 13)
expo-image-picker NSPhotoLibraryUsageDescription, NSCameraUsageDescription (NSMicrophoneUsageDescription for video) CAMERA (and RECORD_AUDIO for video)
expo-location NSLocationWhenInUseUsageDescription ACCESS_COARSE_LOCATION, ACCESS_FINE_LOCATION
expo-document-picker none (iCloud documents need the iCloud entitlement) none
expo-sharing none none

Custom icons (e.g. Lucide)

Override any built-in icon

Built-in icons are the official Lucide glyphs, rendered via the optional react-native-svg peer when it is installed, or drawn with Views (no dependency) otherwise. Override any of them via the icons prop - the built-in icon is used for anything you don't override:

import { Send, Mic } from 'lucide-react-native'

<Chat
  icons={{
    send: ({ color, size }) => <Send color={color} size={size} />,
    mic:  ({ color, size }) => <Mic color={color} size={size} />,
  }}
  {...props}
/>

Overridable names: send, mic, camera, play, pause, check, checkAll, clock, pin, plus, close, chevronLeft, chevronDown, emoji, paperclip, reply, pencil, lock, trash.


Support This Project

I maintain this project in my free time with no compensation. If you find it useful and want to help keep it alive, please consider sponsoring. Your support means a lot! 💖

Become a Sponsor


Using an AI coding agent? llms.txt is a condensed integration guide for agents adding this library to an app, and AGENTS.md covers working inside this repository.

📖 Table of Contents


📋 Requirements

React Native React iOS Android Expo TypeScript
>= 0.82.0 >= 19 >= 15.1 API 24+ (7.0) SDK 55+ >= 5.0 (optional)

The floor comes from react-native-gesture-handler 3, which the library is built on (3.0+ is required; it supports React Native 0.82 and newer). The example app runs Expo SDK 58 with React Native 0.88.


📦 Installation

Expo Projects

npx expo install @kesha-antonov/react-native-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller

Bare React Native Projects

Three steps

1. Install the packages. Reanimated 4 also needs react-native-worklets; leave it out on Reanimated 3:

yarn add @kesha-antonov/react-native-chat react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
npm install --save @kesha-antonov/react-native-chat react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller

2. Add the worklets Babel plugin as the last entry in babel.config.js - react-native-worklets/plugin on Reanimated 4, react-native-reanimated/plugin on Reanimated 3 - following the react-native-reanimated installation guide.

3. Install iOS pods, then rebuild the native app (npx react-native run-ios / run-android) and restart Metro with --reset-cache. every peer above ships native code, so reloading the JS bundle alone is not enough:

npx pod-install

Optional peers

Every feature below turns itself on when its package is installed and stays hidden when it is not - there is nothing to configure. getChatCapabilities() reports what the current install can do, e.g. to build UI that matches the chat's. In development, a feature that was asked for but cannot work (say audioRecording={{ isEnabled: true }} without expo-audio) logs one hint.

Package Feature getChatCapabilities() key
expo-clipboard or @react-native-clipboard/clipboard "Copy" in the long-press menu clipboard
expo-haptics Haptic ticks (long-press, swipe-to-reply, recording) haptics
expo-blur Blurred backdrop behind the menu and the round video recorder blur
react-native-svg Lucide icons and vector rings svg
expo-audio Voice playback and hold-to-record voice notes audioPlayback, voiceRecording
react-native-audio-api Voice waveforms, resume and trim waveform
expo-video Inline video and round video notes videoPlayback
react-native-vision-camera 5 In-chat round video capture roundVideoCapture
expo-image-picker System camera fallback for video notes videoRecording
react-native-streamdown Rich streaming markdown markdown
@lodev09/react-native-true-sheet Native attachment sheet nativeSheet
expo-media-library The attachment menu's photo grid mediaLibrary
expo-image-picker The attachment menu's system photo picker and camera imagePicker
expo-document-picker The attachment menu's File tab documentPicker
expo-location The attachment menu's Location tab location
expo-sharing Opening a received file in the share sheet (otherwise Linking) sharing
@react-native-async-storage/async-storage Emoji recents and skin tones kept across launches persistentEmojiRecents
expo-image Gallery thumbnails straight from the photo library -

🔄 Migrating from react-native-gifted-chat

The API, props, and IMessage model are unchanged - migrating is a package swap plus renaming the GiftedChat* identifiers. Full guide with a codemod: docs/MIGRATION.md.

What to rename
yarn remove react-native-gifted-chat
yarn add @kesha-antonov/react-native-chat
react-native-gifted-chat @kesha-antonov/react-native-chat
react-native-gifted-chat @kesha-antonov/react-native-chat
GiftedChat Chat
GiftedAvatar ChatAvatar
GiftedChatContext ChatContext
IMessage, User, useChatContext, … unchanged

🚀 Usage

Basic Example

See Quick start above for the minimal setup. More examples - Slack-style messages, quick replies, custom components - live in the example directory.


📊 Data Structure

Messages, system messages, and quick replies follow the structure defined in Models.ts.

Message object structure
interface IMessage {
  _id: string | number
  text: string
  createdAt: Date | number
  user: User
  image?: string
  /** Tiny stand-in drawn blurred under `image` until it loads: a small image uri, or a blurhash with expo-image */
  imagePlaceholder?: string
  video?: string
  /** Render `video` as a round video note */
  videoNote?: boolean
  audio?: string
  /** Length of `audio` / `video` in seconds */
  duration?: number
  /** The voice or round note has not been played by its recipient yet (unread dot) */
  isMediaUnread?: boolean
  /** View-once voice or round note: plays a single time, then `mediaPlayback.onViewOnceEnd` fires */
  isViewOnce?: boolean
  /** Transcribed text of a voice or round note, shown under it via the transcribe button */
  transcription?: string
  system?: boolean
  sent?: boolean
  received?: boolean
  pending?: boolean
  /** Sending failed: a red badge replaces the checks */
  isFailed?: boolean
  /** The message was edited: its time reads "edited 14:05" */
  isEdited?: boolean
  editedAt?: Date | number
  /** True while the text is still streaming in (shows a typing cursor) */
  streaming?: boolean
  /** Media uploading or downloading: a progress ring with a cancel ✕ ({ type: 'upload' | 'download', progress?, totalBytes? }) */
  transfer?: MediaTransfer
  /** Media not fetched by itself: a download arrow, which calls `mediaTransfer.onDownload` */
  isDownloadRequired?: boolean
  /** A voice note's waveform from the server (0..1, or 0..31 integers), drawn before the audio downloads */
  waveform?: number[]
  quickReplies?: QuickReplies
  replyMessage?: ReplyMessage
  reactions?: MessageReaction[]
  location?: {
    latitude: number
    longitude: number
  }
  /** A document: a file bubble (icon, name, size); a tap opens it */
  file?: {
    uri: string
    name: string
    size?: number
    mimeType?: string
  }
  /** A web page preview under the text (or fetched via `fetchLinkPreview`); `null` hides it */
  linkPreview?: {
    url?: string
    siteName?: string
    title?: string
    description?: string
    image?: string
    imageWidth?: number
    imageHeight?: number
    imageSize?: 'large' | 'small'
  } | null
}

interface ReplyMessage {
  _id: string | number
  text: string
  user: User
  image?: string
  audio?: string
}

interface MessageReaction {
  emoji: string
  userIds: (string | number)[]
}

interface User {
  _id: string | number
  name?: string
  avatar?: string | number | (() => React.ReactNode)
}

📖 Props Reference

Every group below is collapsed - open the one you need.

Core configuration, refs & theming

Core Configuration

  • messages (Array) - Messages to display
  • user (Object) - User sending the messages: { _id, name, avatar }
  • onSend (Function) - Callback when sending a message
  • messageIdGenerator (Function) - Generate an id for new messages. Defaults to a simple random string generator.
  • locale (String) - Locale to localize the dates. You need first to import the locale you need (ie. require('dayjs/locale/de') or import 'dayjs/locale/fr')
  • colorScheme ('light' | 'dark') - Force color scheme (light/dark mode). When set to 'light' or 'dark', it overrides the system color scheme. When undefined, it uses the system color scheme. Default is undefined.
  • theme (Object) - Override the default light theme tokens (colors / radii / spacing / typography / avatar / sendButton / composer / voice / bubble / wallpaper / nameColors). Deep-merged over defaultLightTheme; any subset is allowed. See Theming & Dark Mode.
  • renderWallpaper (Function | null) - The chat background. By default Chat draws a swirl gradient from theme.wallpaper, turning one step per message you send. Return your own element (an image, ChatWallpaper with other props...) to replace it, or pass null for the plain theme.colors.background.
  • darkTheme (Object) - Same as theme, applied when the resolved color scheme is dark (deep-merged over defaultDarkTheme).
  • icons (Object) - Icon override registry. Supply a render function for any built-in icon to replace it (e.g. with lucide-react-native). See Custom icons.
  • labels (Object) - Override any UI string. See Localization (i18n).

Refs

  • messagesContainerRef (LegendListRef) - Ref to the message list, a Legend List ref: scrollToEnd, scrollToKey (keys are message _ids as strings), scrollToIndex, getState. Indexes count from the oldest message
  • textInputRef (TextInput ref) - Ref to the text input
  • chatRef (ChatHandle ref) - chatRef.current.scrollToMessage(id, { animated, viewPosition, isHighlighted }) scrolls to a message, also one far up the history, and with isHighlighted flashes it the way a tapped quote does. For a search result or a deep link
Keyboard & layout

Keyboard & Layout

  • bottomInset (Number) - The composer's space for the home indicator; measured by default. Pass it when the host already knows it, e.g. a chat inside a sliding panel whose own inset arrives late. It is still given up while the keyboard or the emoji panel covers it

  • keyboardProviderProps (Object) - Props to be passed to the KeyboardProvider for keyboard handling. No defaults are applied - in particular Chat does not set statusBarTranslucent / navigationBarTranslucent, because on Android those change the activity window and the change outlives the chat screen (#2755). react-native-keyboard-controller turns them on by itself when the app is genuinely edge-to-edge, so there is nothing to set in a normal app.

    Only used when Chat mounts the provider itself. If your app already mounts a KeyboardProvider (the setup react-native-keyboard-controller recommends - once, at the root), Chat detects it and reuses it instead of nesting a second one, and this prop is ignored. Configure the provider where you mount it.

  • enableKeyboardProvider (Bool) - Render the built-in KeyboardProvider; default is true. You do not need to turn this off just because your app mounts its own provider - that case is detected and reused. Set it to false only to opt out completely, e.g. when the provider's edge-to-edge behavior causes layout shift or a header jump on Android/Expo.

  • enableGestureHandlerRootView (Bool) - Render the GestureHandlerRootView Chat mounts around itself; default is true. Unlike KeyboardProvider, an existing one can't be auto-detected - react-native-gesture-handler doesn't expose that publicly - so set this to false yourself if your app (or a library it uses, e.g. a bottom sheet) already mounts one at the root. Nesting a second one changes the native view hierarchy around the composer, which has been observed to make a rare Fabric/Yoga layout assertion on iOS more likely, especially when Chat is mounted and unmounted while the keyboard is open (#17).

  • keyboardAvoidingViewProps (Object) - Props to be passed to the KeyboardAvoidingView. See keyboardVerticalOffset below for proper keyboard handling.

  • isAlignedTop (boolean | 'auto') - Where the bubbles sit while the whole conversation fits on screen; once it is taller than the list this has no effect. false (default) keeps the usual bottom-anchored chat, true pins the messages to the top, and 'auto' pins them to the top while the keyboard is closed and re-anchors them to the bottom while it is open - so a short conversation starts under the header and moves above the keyboard when the composer is focused (#2736). Works with either isInverted setting.

  • isInverted (Bool) - Reverses display order of messages; default is true

Understanding keyboardVerticalOffset

keyboardVerticalOffset tells the KeyboardAvoidingView how far down the screen its container starts. That distance depends on the navigation header and on anything else you render above the chat.

You do not normally need to set it. Chat measures its own position on screen and uses that, so the input toolbar sits on the keyboard whether the chat is full-screen or under a navigation header. The measurement comes from the SafeAreaProvider frame and updates on rotation and layout changes.

Pass your own value only to add extra space above the keyboard - it replaces the measured one:

<Chat keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight + 16 }} />

If you do, sanity-check it on device: a toolbar behind the keyboard means the value is too small, a gap above the keyboard means it is too large. useHeaderHeight() is the usual source, but some navigator setups report a value that does not match the header you actually render.

Upgrading from 4.1.0 or earlier: the default used to be insets.top, which could not account for a navigation header - so most apps passed useHeaderHeight() to compensate. That is no longer needed; drop it and let Chat measure, or the toolbar will float above the keyboard by the header height.

Text input, composer & actions

Text Input & Composer

  • text (String) - Input text; default is undefined, but if specified, it will override Chat's internal state. Useful for managing text state outside of Chat (e.g. with Redux). Don't forget to implement textInputProps.onChangeText to update the text state.
  • initialText (String) - Initial text to display in the input field
  • onDraftChange (Function) - (draft: string) => void, the user's unsent text as it changes ('' once sent). Editing a message sets the draft aside and brings it back afterwards, without reporting the edited text. Save it with the chat and pass it back as initialText
  • isSendButtonAlwaysVisible (Bool) - Always show send button in input text composer, disabled while there is nothing to send. By default it shows only with text when voice or video notes can be recorded (their button takes the slot while the composer is empty), and always when neither can
  • isTextOptional (Bool) - Allow sending messages without text (useful for media-only messages); default false. Use with isSendButtonAlwaysVisible for media attachments.
  • isMultiline (Bool) - Whether the composer accepts multiple lines; default true. With true the return key inserts a newline and you send with the send button. Set false for a single-line composer whose return key sends the message (the keyboard's return key becomes "send" and stays open afterwards).
  • renderInputToolbar (Component | Function) - Custom message composer container
  • renderComposer (Component | Function) - Custom text input message composer
  • renderSend (Component | Function) - Custom send button; you can pass children to the original Send component quite easily, for example, to use a custom icon (example)
  • renderActions (Component | Function) - Custom action button on the left of the message composer
  • renderAccessory (Component | Function) - Custom second line of actions below the message composer
  • emojiKeyboard (Bool | Object) - The built-in emoji keyboard behind the composer's emoji button, on by default. It opens in the system keyboard's place at the last keyboard height (200 + the bottom inset before a keyboard was seen) and inserts at the caret, whether or not you control text. false hides the emoji button. An object configures it: { isEnabled?, columns?, categories?, recents?, isSearchEnabled?, renderEmojiKeyboard? } - columns fixes the column count (default: as many 45pt columns as fit); categories picks and orders the tabs ('smileys' | 'animals' | 'food' | 'activities' | 'travel' | 'objects' | 'symbols' | 'flags'); recents is false or { isEnabled?, storageKey?, isPersisted? } (persisted through @react-native-async-storage/async-storage when installed); isSearchEnabled (default true); renderEmojiKeyboard({ onSelect, onBackspace, onClose, height, bottomInset }) draws your own keyboard in the panel. Colors and sizes live in theme.emojiKeyboard.
  • onPressEmoji (Function) - Called when the emoji button is pressed, instead of opening the built-in emoji keyboard. Passing it shows the button even with emojiKeyboard={false}.
  • audioRecording (Bool | Object) - Hold-to-record voice notes, on by default when expo-audio is installed; false (or { isEnabled: false }) turns them off. An object configures them: { isEnabled?, minDurationMs?, maxDurationMs?, isViewOnceEnabled?, onPermissionDenied?, onTooShort?, onError? }. isViewOnceEnabled shows a view-once toggle above the pause button while a take is locked or paused; a take sent with it on reaches onSend with isViewOnce: true. minDurationMs (default 700) drops takes that long or shorter and calls onTooShort; maxDurationMs (default 600000) sends the take when reached. Requires the optional expo-audio peer (and react-native-audio-api for the playback waveform); the mic button is hidden when it is absent. A paused take can be resumed when react-native-audio-api is installed with FFmpeg (the M4A recordings are joined without re-encoding), and trimmed when expo-file-system is installed too; a trimmed take reaches onSend as a 16-bit mono WAV at 24kHz, an untrimmed one as the recorder's M4A.
  • videoRecording (Bool | Object) - Round video notes, on by default when react-native-vision-camera is installed; false (or { isEnabled: false }) turns them off. true / { isEnabled: true } also offers the system-camera fallback below when vision-camera is missing. An object configures them: { isEnabled?, maxDuration?, minDurationMs?, isViewOnceEnabled?, onPermissionDenied?, onTooShort?, onError? }. maxDuration is in seconds (default 60); minDurationMs (default 800) drops shorter takes and calls onTooShort; isViewOnceEnabled works as in audioRecording, for round notes recorded with vision-camera. With react-native-vision-camera 5 or newer linked (plus its react-native-nitro-modules and react-native-nitro-image peers; it has no Expo config plugin, so add NSCameraUsageDescription/NSMicrophoneUsageDescription and the CAMERA/RECORD_AUDIO permissions yourself), the record button records a note on the first hold - shared with voice notes when both are enabled, on its own otherwise. Reaching maxDuration stops into a preview (sends directly without expo-video). Without vision-camera it falls back to expo-image-picker's system camera, which sends a plain (non-round) video.
  • mediaPlayback (Object) - How voice and round video notes play. { isAutoPlayNextEnabled?, playbackRate?, onPlaybackRateChange?, isRoundVideoAutoplayEnabled?, isNowPlayingBarEnabled?, isFloatingRoundNoteEnabled?, onMediaRead?, isNearEar?, onTranscribe?, onViewOnceEnd? }. isNowPlayingBarEnabled (default true) shows a "now playing" bar at the top of the chat while a note plays or is paused. isFloatingRoundNoteEnabled (default true) keeps a round note that is playing or paused going in a small draggable circle over the list once its row scrolls out of view; set it to false to stop the note with its row instead. isAutoPlayNextEnabled (default true) starts the next newer voice or round note in the chat when one plays to its end. The playback speed is shared by every note; playbackRate sets it, and onPlaybackRateChange reports changes so the app can keep the speed across launches. isRoundVideoAutoplayEnabled (default false) loops round notes silently in the list instead of holding their first frame. onMediaRead(message) is called when an incoming note with isMediaUnread starts playing, so the app can mark it listened. isNearEar is raise to listen: feed it from the app's proximity sensor, and while it is true the current voice or round note plays through the earpiece (restarting if it was under a second in); when it goes back to false the note pauses and the speaker route returns. onTranscribe(message) shows a transcribe button on voice notes and beside round notes; tapping it calls this, shows a loading outline until the app sets message.transcription, then opens the text under the waveform, or in a bubble under the round note (tap again to collapse or expand). onViewOnceEnd(message) is called once a view-once note (isViewOnce) has played to its end or been stopped after starting, so the app can remove it. A view-once round note carries the "1" marker on its play button, never autoplays or floats, and cannot be scrubbed.
  • textInputProps (Object) - props to be passed to the <TextInput>.

Composer height - there are no height props. The composer starts one line tall and grows with its content. Constrain it through textInputProps.style (e.g. { maxHeight: 120 }), which is applied after the measured height and wins.

Actions & Action Sheet

  • attachments (Bool | Object) - The built-in attachment menu behind the composer's paperclip, on by default; the paperclip shows when at least one tab's peer is installed. Tabs: gallery (an in-sheet grid with expo-media-library, the system picker with expo-image-picker otherwise), camera (expo-image-picker; a tab of its own only without the grid, which has a camera tile), file (expo-document-picker) and location (expo-location). Picks are sent through onSend: one image / video message per photo or video with the caption on the first, a file message per document, a location message. false hides the paperclip. An object configures it: { isEnabled?, tabs?, pickers?, onPick?, renderAttachmentMenu? } - tabs picks and orders them; pickers ({ gallery?, camera?, file? }, each an async () => PickedAttachment[] that returns [] on cancel) replaces the Expo pickers with your own, for an app that picks with other libraries, and shows that tab without its Expo peer; isGalleryGridEnabled: false leaves Gallery to the system picker instead of the in-sheet grid, for an app without Android's READ_MEDIA_IMAGES / READ_MEDIA_VIDEO; onPick(attachments, { caption }) intercepts the picks (PickedAttachment[]) and returns the messages to send, null to send nothing, or nothing for the default; renderAttachmentMenu({ visible, onClose, tabs, onSend }) draws your own menu. Colors live in theme.attachments. actions, onPressActionButton and renderActions take precedence. See Emoji keyboard and attachment menu for the permissions each peer needs.
  • actions (Array) - Action options for the composer "+" button. Array of { title, action }; add icon (and optional color) to an action to render an attachment grid (tiles) instead of a list. Opens the built-in themed AttachmentSheet - no extra dependency.
  • onPressActionButton (Function) - Callback when the "+" button is pressed (if set, the built-in AttachmentSheet is not shown)
  • actionSheet (Function) - Escape hatch for a custom system action sheet. The bundled @expo/react-native-action-sheet dependency was removed, so context.actionSheet() defaults to a no-op; pass your own implementation (with ActionSheetProvider in your tree) if you relied on it.
  • actionSheetOptionTintColor (String) - Tint color for action labels in the attachment sheet
Messages, container & bubbles

Messages & Message Container

  • messagesContainerStyle (Object) - Custom style for the messages container
  • renderMessage (Component | Function) - Custom message container
  • renderLoading (Component | Function) - Render a loading view while the chat measures its layout on mount
  • isLoading (Boolean) - The history is loading. Over an empty list the chat shows a spinner in a service-colored circle (a 28 arc in a 36 circle, growing in from 0.3 over 150ms) in place of the empty-chat card. Messages already passed stay visible, without the spinner
  • mediaTransfer (Object) - Handlers for the media transfer buttons. { onDownload?, onCancel? }. A message with transfer: { type, progress?, totalBytes? } draws the progress ring with a cancel ✕ over its photo, video, file, voice or round note (with "1.2 MB / 4.5 MB" when totalBytes or the file size is known); tapping it calls onCancel(message). A message with isDownloadRequired draws the download arrow; tapping it calls onDownload(message). Without onDownload, a voice note or photo then fetches itself. Remote voice notes, photos and round notes that need no app handling show the same ring while they load, from the request's own progress
  • renderChatEmpty (Function | null) - What to show while there are no messages. By default a greeting card: "No messages here yet...", a line of help and a big 👋 that sends itself when tapped, centered over the wallpaper. Return your own element to replace it, or pass null for nothing. The card is exported as ChatEmpty.
  • emptyChatGreeting (String | null) - The greeting on the empty-chat card, sent as a message when tapped; default '👋'. null keeps just the title.
  • firstUnreadMessageId (String | Number | null) - The first message the user has not read. A full-width "Unread Messages" bar is drawn above it and the chat opens scrolled so the bar is at the top. Keep it fixed while the chat is open (the bar stays until you leave), e.g. computed once from the unread count when the screen mounts.
  • renderUnreadSeparator (Function | null) - Custom "Unread Messages" bar, or null to only scroll to the first unread message. The default is exported as UnreadSeparator.
  • renderChatFooter (Component | Function) - Custom component to render below the MessagesContainer (separate from the ListView)
  • listProps (Object) - Extra props for the message list, an AnimatedLegendList (e.g. drawDistance, maintainScrollAtEnd, onViewableItemsChanged). The list renders oldest first, not inverted, so onEndReached fires at the newest message. Handlers the list uses itself (onScrollBeginDrag / onScrollEndDrag, onMomentumScrollBegin / onMomentumScrollEnd, onContentSizeChange, onItemSizeChanged, onMetricsChange, onLayout, the viewability callbacks) run after its own, and contentContainerStyle goes on top of its padding.

Message Bubbles & Content

  • renderBubble (Component | Function(props: BubbleProps)) - Custom message bubble. Receives BubbleProps as parameter.
  • renderMessageText (Component | Function) - Custom message text
  • renderMessageImage (Component | Function) - Custom message image. The built-in one opens the photo viewer on tap: it pages through every photo in the chat, oldest first, with a "3 of 12" counter, the caption, sender and date; pinch or double-tap zooms, and a swipe up or down closes it
  • renderMessageVideo (Component | Function) - Custom message video
  • renderMessageAudio (Component | Function) - Custom message audio
  • renderMessageLocation (Component | Function) - Custom renderer for IMessage.location; defaults to a map card that opens the system maps app on tap
  • renderMessageFile (Component | Function) - Custom renderer for IMessage.file; defaults to a document bubble (a circle with the extension, the name, the size) that opens the file in the share sheet (expo-sharing) or through Linking on tap
  • messageActions (Array | Function(message, defaults)) - Long-press context menu actions. Each item is { key?, label, icon?, onPress, destructive? }. An array replaces the built-in actions; a function receives the message and the built-in actions for it and returns what to show, so you can extend, filter or reorder them. See Message actions.
  • defaultMessageActions (Bool | MessageActionKey[]) - The built-in actions, in this order: reply, copy, forward, pin, edit, select, delete. Default true (all that can work); an array picks and orders them; false turns them off. Each shows only when it can work: Reply when reply.isEnabled is not false; Copy for messages with text when expo-clipboard or @react-native-clipboard/clipboard is installed; Edit on your own text messages when onEditMessage is set; Forward / Pin / Delete when their callbacks are set; Select when a selection can be acted on (a clipboard, Forward or Delete). They are also off when onLongPressMessage is set and messageActions is not, so an app that handles long-press itself keeps doing so.
  • onEditMessage (Function(message, text)) - Turns on the "Edit" action for your own text messages. Edit puts the text in the composer under an "Editing" banner; sending then calls this instead of onSend. Closing the banner cancels the edit.
  • onDeleteMessage (Function(message)) - Turns on the "Delete" action (not red).
  • onRetryMessage (Function(message)) - Turns on "Retry" for your own messages that failed to send (isFailed), first in their menu above Delete, whatever defaultMessageActions lists.
  • highlightText (String) / highlightTextStyle (TextStyle) - Words to mark in every message's text, links included (case-insensitive), e.g. the query of a search in the chat; yellow behind black text by default.
  • onForwardMessage (Function(message)) - Turns on the "Forward" action.
  • onForwardMessages (Function(messages)) - Forwards the messages checked in selection mode, oldest first (also turns on "Forward"). Without it the selection bar's Forward calls onForwardMessage once per message.
  • onDeleteMessages (Function(messages)) - Deletes the messages checked in selection mode, oldest first (also turns on "Delete"). Without it the selection bar's Delete calls onDeleteMessage once per message.
  • onSelectionChange (Function(messages)) - Multi-select: "Select" in the long-press menu checks the message, a tap checks or unchecks others (check circles on the left, a tinted row), and a bar replaces the composer with the count, Copy (texts joined oldest first), Forward and Delete. Called on every change with the checked messages; with [] once it ends (the X, Android's back, or the last message unchecked).
  • renderSelectionBar (Function({ count, actions, onClose, messages }) | null) - Custom bar in the composer's place while selecting, or null to keep the composer and drive the selection from your own header through onSelectionChange.
  • fetchLinkPreview (Function(url) => Promise<LinkPreview | null>) - A web page preview (accent bar, site name, bold title, description, picture full width or as a 48dp thumbnail) is drawn under the text for any message with linkPreview data. For messages without it, this fetches one for the first link in the text, e.g. from your server's Open Graph endpoint; each URL is fetched once per app run. IMessage.linkPreview: null turns it off for one message.
  • renderLinkPreview (Function({ preview, currentMessage, position, maxWidth, onPress }) | null) - Custom link preview, or null to draw none. The default is exported as LinkPreviewCard.
  • onPressLinkPreview (Function(preview, message)) - Called when a link preview is tapped, instead of opening its URL.
  • onPinMessage (Function(message)) - Turns on the "Pin" action; it reads "Unpin" on a message with isPinned: true. Toggle isPinned in the handler.
  • renderCustomView (Component | Function) - Custom view inside the bubble
  • isCustomViewBottom (Bool) - Determine whether renderCustomView is displayed before or after the text, image and video views; default is false
  • onPressMessage (Function(context, message)) - Callback when a message bubble is pressed
  • onLongPressMessage (Function(context, message)) - Callback when a message bubble is long-pressed; you can use this to show action sheets (e.g., copy, delete, reply). Setting it (without messageActions) turns the built-in long-press menu off
  • isMessageGestureEnabled (Bool | Function(message)) - Whether the bubble itself is part of the row's tap / long-press surface that reactions and messageActions rely on; default is true. Pass false, or a predicate, for messages that render natively interactive content - the row beside the bubble stays pressable either way. See Interactive content inside bubbles.
  • imageProps (Object) - Extra props to be passed to the <Image> component created by the default renderMessageImage
  • imageStyle (Object) - Custom style for message images
  • videoProps (Object) - Extra props to be passed to the video component created by the required renderMessageVideo
  • messageTextProps (Object) - Extra props to be passed to the MessageText component. Useful for customizing link parsing behavior, text styles, and matchers:
    • matchers - Custom matchers for linking message content (like URLs, phone numbers, hashtags, mentions)
    • linkStyle - Custom style for links
    • email / phone / url - Enable/disable parsing (default: true)
    • hashtag / mention - Enable/disable parsing (default: false)
    • hashtagUrl / mentionUrl - Base URLs (e.g. 'https://x.com/hashtag')
    • stripPrefix - Strip 'http://' or 'https://' from URL display (default: false)
    • TextComponent - Custom Text component to use (e.g., from react-native-gesture-handler)

A custom matcher, replacing the default phone linking with an action sheet:

<Chat
  messageTextProps={{
    phone: false, // Disable default phone number linking
    matchers: [
      {
        type: 'phone',
        pattern: /\+?[1-9][0-9\-\(\) ]{7,}[0-9]/g,
        getLinkUrl: (replacerArgs: ReplacerArgs): string => {
          return replacerArgs[0].replace(/[\-\(\) ]/g, '')
        },
        getLinkText: (replacerArgs: ReplacerArgs): string => {
          return replacerArgs[0]
        },
        style: styles.linkStyle,
        onPress: (match: CustomMatch) => {
          const url = match.getAnchorHref()

          const options: {
            title: string
            action?: () => void
          }[] = [
            { title: 'Copy', action: () => setStringAsync(url) },
            { title: 'Call', action: () => Linking.openURL(`tel:${url}`) },
            { title: 'Send SMS', action: () => Linking.openURL(`sms:${url}`) },
            { title: 'Cancel' },
          ]

          showActionSheetWithOptions({
            options: options.map(o => o.title),
            cancelButtonIndex: options.length - 1,
          }, (buttonIndex?: number) => {
            if (buttonIndex === undefined)
              return

            const option = options[buttonIndex]
            option.action?.()
          })
        },
      },
    ],
    linkStyle: { left: { color: 'blue' }, right: { color: 'lightblue' } },
  }}
/>

See the full example in LinksExample.

Avatars, username, date & time, system messages

Avatars

Avatars and sender names show in group chats only: a one-to-one chat has neither.

  • isGroupChat (Bool) - Whether this is a group chat; default is auto-detected (more than one other sender in messages means a group)
  • isAvatarVisible (Bool) - Show avatars beside incoming messages; default true in group chats, false in one-to-one chats, and true whenever renderAvatar is a function. Pass true to keep avatars in one-to-one chats
  • renderAvatar (Component | Function) - Custom message avatar; set to null to not render any avatar for the message
  • isUserAvatarVisible (Bool) - Whether to render an avatar for the current user; default is false, only show avatars for other users
  • isAvatarVisibleForEveryMessage (Bool) - When false, avatars will only be displayed when a consecutive message is from the same user on the same day; default is false
  • onPressAvatar (Function(user)) - Callback when a message avatar is tapped
  • onLongPressAvatar (Function(user)) - Callback when a message avatar is long-pressed
  • isAvatarOnTop (Bool) - Render the message avatar at the top of consecutive messages, rather than the bottom; default is false

Username

  • isUsernameVisible (Bool) - Show the sender's name on the first message of each run of incoming messages; default true in group chats and false in one-to-one chats (see isGroupChat)
  • renderUsername (Component | Function) - Custom Username container

Date & Time

  • timeFormat (String) - Format to use for rendering times; default is 'LT' (see Day.js Format)

  • dateFormat (String) - Format to use for rendering dates; default is 'D MMMM' (see Day.js Format)

  • dateFormatCalendar (Object) - Format to use for rendering relative times; default is { sameDay: '[Today]' } (see Day.js Calendar)

  • renderDay (Component | Function) - Custom day above a message. This is also how the day label is styled - it receives DayProps (createdAt, dateFormat, dateFormatCalendar, containerStyle, wrapperStyle, textProps, isAnimated), so render the built-in Day with the styles you want:

    import { Chat, Day, DayProps } from '@kesha-antonov/react-native-chat'
    
    <Chat
      renderDay={(props: DayProps) => (
        <Day {...props} wrapperStyle={{ backgroundColor: '#eee' }} textProps={{ style: { color: '#333' } }} />
      )}
    />
    

    isAnimated is true for the floating header that sticks to the top while scrolling and false for the inline separators, so one function can style them differently.

  • renderTime (Component | Function) - Custom time inside a message

  • timeTextStyle (Object) - Custom text style for time inside messages (supports left/right styles)

  • isDayAnimationEnabled (Bool) - Enable animated day label that appears on scroll; default is true

System Messages

  • renderSystemMessage (Component | Function) - Custom system message
Load earlier, typing indicator, quick replies, scroll to bottom

Load Earlier Messages

  • loadEarlierMessagesProps (Object) - Props to pass to the LoadEarlierMessages component. The button is only visible when isAvailable is true:
    • isAvailable - Controls button visibility (default: false)
    • onPress - Callback when button is pressed
    • isLoading - Shows a loading cell, a spinner in a 36 service circle, in place of the button (default: false)
    • isInfiniteScrollEnabled - Enable infinite scroll up when reaching the top of messages container, automatically calls onPress (not yet supported for web). The list then ends in the loading cell instead of a button while isAvailable
    • label - Override the default "Load earlier messages" text
    • containerStyle / wrapperStyle / textStyle - Custom styles for the button
    • activityIndicatorStyle - Custom style for the loading indicator
    • activityIndicatorColor - Color of the spinner's arc (default: the date pill's text color)
    • activityIndicatorSize - Deprecated and ignored: the spinner is a fixed 28 arc
  • renderLoadEarlier (Component | Function) - Custom "Load earlier messages" button

Typing Indicator

  • isTyping (Bool) - Typing Indicator state; default false. If you use renderFooter it will override this.
  • renderTypingIndicator (Component | Function) - Custom typing indicator component
  • typingIndicatorStyle (StyleProp) - Custom style for the TypingIndicator component.
  • renderFooter (Component | Function) - Custom footer component on the ListView, e.g. 'User is typing...'; see CustomizedRenderingExample.tsx for an example. Overrides default typing indicator that triggers when isTyping is true; the indicator comes as the second argument, renderFooter(props, typingIndicator), to keep it next to your own footer.
  • TypingStatus (Component) - The messenger way to show it: in your chat header, three dots that swell in turn before "typing" (waves for a recording, arrows for an upload). <TypingStatus users={typingUsers} action='recordingVoice' isGroup color={accent} /> reads "typing", "Anna is typing", "Anna and Max are typing", "recording a voice message"... ChatList rows use it for typingUsers / typingAction, and getTypingText gives the text alone

Quick Replies

See the quick replies example in messages.ts.

  • onQuickReply (Function) - Callback when sending a quick reply (to backend server)
  • renderQuickReplies (Function) - Custom all quick reply view
  • quickReplyStyle (StyleProp) - Custom quick reply view style
  • quickReplyTextStyle (StyleProp) - Custom text style for quick reply buttons
  • quickReplyContainerStyle (StyleProp) - Custom container style for quick replies
  • renderQuickReplySend (Function) - Custom quick reply send view

Scroll to Bottom

The button comes up after you scroll back towards the newest message by scrollToBottomOffset, or when a message arrives while you are away from the newest one, and goes away at the newest message (or after scrolling away again by the same distance, when scrolling brought it up). Messages that arrive while you are away are counted in a badge, which counts down as each one scrolls into view.

  • isScrollToBottomEnabled (Bool) - Show the scroll-to-bottom button; default true. Passing true explicitly also keeps the older behaviour of a non-inverted list scrolling to its end on layout
  • isScrollToBottomBadgeEnabled (Bool) - Count new messages in a badge on the button; default true
  • scrollToBottomComponent (Function) - Custom Scroll To Bottom Component container
  • scrollToBottomOffset (Integer) - How far to scroll before the button shows or hides; default 100
  • scrollToBottomStyle (Object) - Custom style for Scroll To Bottom wrapper (position, bottom, right, etc.)
  • scrollToBottomContentStyle (Object) - Custom style for Scroll To Bottom content (size, background, shadow, etc.)

🧩 Guides

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)
Prop What it does
chats Every chat, archived ones included
user You: "You:" in groups and the checks on your own last messages
onPressChat / onLongPressChat A tap; a long-press (default: select)
onPinChats / onMuteChats / onArchiveChats / onDeleteChats Selection actions; archive also by swiping a row
onReorderPinnedChats Turns on dragging pinned chats; receives the new order of ids
onPressNewChat Shows the new-chat button
isLoading The loading placeholder
isSortEnabled Pinned first, then by newest message (default true)
isDeleteConfirmed / isSwipeEnabled Ask before deleting; swipe to archive (both default true)
isHeaderVisible / title / renderHeaderRight / isTopInsetApplied The built-in header (hide it to use your navigator's)
headerRightPosition renderHeaderRight before the search button (default) or 'afterSearch', e.g. for a close button
timeFormat / dateFormat dayjs 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 / onSearchChange Search; a custom match; a server-side search
isArchiveOpen / onArchiveOpenChange Control which list shows
renderChat / renderEmpty / listProps / style A custom row (ChatListCell is the built-in one), the empty text, FlatList props (onEndReached, refreshControl...)
theme / darkTheme / colorScheme / locale / labels / icons As on Chat; 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 />}
/>

Reply to Messages

Swipe-to-reply, reply preview and threading

Swipe on a message to reply to it, showing a reply preview in the input toolbar and the replied message above the new bubble. Uses ReanimatedSwipeable from react-native-gesture-handler plus react-native-reanimated.

Basic Usage

<Chat
  messages={messages}
  onSend={onSend}
  user={{ _id: 1 }}
  reply={{
    swipe: {
      isEnabled: true,
      direction: 'left', // swipe left to reply
    },
  }}
/>

Replying works out of the box: long-press a message and pick Reply, or swipe it left. The swipe takes over from the list after 0.4cm (about 25pt) of mostly sideways travel, the row follows the finger up to 80pt, a reply arrow fades in from 20pt and fills by 50pt, where a light haptic ticks; letting go past 50pt starts the reply, and the row slides back over 180ms. Turn the swipe off with reply={{ swipe: { isEnabled: false } }}, or all replying with reply={{ isEnabled: false }}.

Tapping a quote inside a bubble scrolls to the quoted message and highlights its row for a second, then fades it out over 300ms. The scroll-to-bottom button then comes up, and its first tap takes you back to the message you tapped the quote in. Pass reply.onPress(replyMessage, message) to do something else.

Reply Props (Grouped)

interface ReplyProps<TMessage> {
  isEnabled?: boolean                // The menu's Reply and swipe-to-reply; default true
  onReply?: (message: TMessage) => void  // A reply started (menu or swipe); use with a controlled `message`

  // Swipe gesture configuration
  swipe?: {
    isEnabled?: boolean              // Swipe-to-reply; default true (false to turn it off)
    direction?: 'left' | 'right'     // Swipe direction; default 'left'
    onSwipe?: (message: TMessage) => void  // Callback when swiped
    renderAction?: (                 // Custom swipe action component
      progress: SharedValue<number>,
      translation: SharedValue<number>,
      position: 'left' | 'right'
    ) => React.ReactNode
    actionContainerStyle?: StyleProp<ViewStyle>
  }

  // Reply preview styling (above input toolbar)
  previewStyle?: {
    containerStyle?: StyleProp<ViewStyle>
    textStyle?: StyleProp<TextStyle>
    imageStyle?: StyleProp<ImageStyle>
  }

  // In-bubble reply styling
  messageStyle?: {
    containerStyle?: StyleProp<ViewStyle>
    containerStyleLeft?: StyleProp<ViewStyle>
    containerStyleRight?: StyleProp<ViewStyle>
    textStyle?: StyleProp<TextStyle>
    textStyleLeft?: StyleProp<TextStyle>
    textStyleRight?: StyleProp<TextStyle>
    imageStyle?: StyleProp<ImageStyle>
  }

  // Callbacks and state
  message?: ReplyMessage             // Controlled reply state
  onClear?: () => void               // Called when reply cleared
  onPress?: (message: ReplyMessage) => void  // Quote tapped; default jumps to the quoted message and flashes it

  // Custom renderers
  renderPreview?: (props: ReplyPreviewProps) => React.ReactNode
  renderMessageReply?: (props: MessageReplyProps) => React.ReactNode
}

ReplyMessage Structure

interface ReplyMessage {
  _id: string | number
  text: string
  user: User
  image?: string
  audio?: string
}

Advanced Example with External State

const [replyMessage, setReplyMessage] = useState<ReplyMessage | null>(null)

<Chat
  messages={messages}
  onSend={messages => {
    const newMessages = messages.map(msg => ({
      ...msg,
      replyMessage: replyMessage || undefined,
    }))
    setMessages(prev => Chat.append(prev, newMessages))
    setReplyMessage(null)
  }}
  user={{ _id: 1 }}
  reply={{
    swipe: {
      isEnabled: true,
      direction: 'right',
      onSwipe: setReplyMessage,
    },
    message: replyMessage,
    onClear: () => setReplyMessage(null),
    onPress: (msg) => scrollToMessage(msg._id),
  }}
/>

Smooth Animations

The reply preview animates automatically - it expands from zero height with a fade-in when it appears, collapses with a fade-out when cleared, and transitions smoothly when you reply to a different message. These use react-native-reanimated for 60fps performance.

Maintaining Scroll Position (AI Chatbots)

Keep the reading position while long answers stream in

The list follows new content only while it is at the newest message. Scrolled up, the reading position stays put while a long answer streams in or new messages arrive, and the scroll-to-bottom button counts them. Both are Legend List behaviours (maintainScrollAtEnd, maintainVisibleContentPosition) that the chat turns on; override them through listProps:

// Never follow new content, even at the newest message
<Chat listProps={{ maintainScrollAtEnd: false }} />

Streaming (AI) Messages

Render AI assistant replies token-by-token. Incoming chunks are batched with requestAnimationFrame (one render per frame, only the streaming bubble re-renders) and a blinking caret shows while a message is still streaming.

AI reply streaming token-by-token and rendering as markdown, with a blinking caret and a Stop button in the composer

useStreamingMessages, stop control and a full example

The reply above streams in token-by-token (note the caret ▋) and renders as markdown - bold, italics, lists, inline and fenced code - while the app swaps the send button for a Stop control mid-stream (with renderSend, below). See Markdown rendering for AI replies to enable markdown.

  • IMessage.streaming - flag a message as streaming (shows the caret)
  • useStreamingMessages(...) - owns the message list, rAF-batches push(), and supports stop via AbortController. It returns { messages, setMessages, append, startStream, isStreaming, stop }; setMessages is there for anything the hook does not cover, so you can patch a message with a plain map.
import { useCallback } from 'react'
import { Chat, IMessage, Send, SendProps, useStreamingMessages } from '@kesha-antonov/react-native-chat'

function Bot () {
  const { messages, append, startStream, isStreaming, stop } = useStreamingMessages<IMessage>()

  const onSend = useCallback((newMessages: IMessage[] = []) => {
    append(newMessages[0])                      // show the user's message
    const stream = startStream({ user: { _id: 2, name: 'Assistant' } }) // empty streaming bubble

    runMyModel(newMessages[0].text, {
      signal: stream.signal,                    // aborts when stop() is called
      onToken: token => stream.push(token),     // batched, one render per frame
      onDone: () => stream.done(),              // clears the streaming flag
    })
  }, [append, startStream])

  // While a reply streams, the send button becomes a Stop button.
  const renderSend = useCallback(
    (sendProps: SendProps<IMessage>) =>
      isStreaming ? <MyStopButton onPress={stop} /> : <Send {...sendProps} />,
    [isStreaming, stop]
  )

  return <Chat messages={messages} onSend={onSend} user={{ _id: 1 }} renderSend={renderSend} />
}

See docs/STREAMING.md for the full hook API and a real Claude streaming adapter (via a backend proxy). A runnable demo lives in example/components/chat-examples/AIBotExample.tsx.

Markdown rendering for AI replies

Built-in renderer, or react-native-streamdown

AI/LLM replies are usually markdown (bold, lists, fenced code). Enable markdown with messageTextProps={{ markdown: true }} (streamed messages auto-render as markdown unless you pass markdown={false}):

// Force markdown for every message:
<Chat messageTextProps={{ markdown: true }} {...props} />

// Streamed messages auto-render as markdown; disable with markdown: false.

There are two renderers and you get the best available one automatically:

  • Built-in, zero-dependency renderer (default). Covers headings, bullet/ordered lists, blockquotes, fenced + inline code, bold/italic/strikethrough, and links. It handles streaming-incomplete markdown gracefully (a half-written **bold or an unclosed code fence renders as plain text until complete), so it's safe to feed token-by-token. Nothing to install. Exposed as BasicMarkdown if you want to use it directly.

  • react-native-streamdown (optional upgrade). When installed it's used instead, for richer streaming-safe markdown (tables, partial-table handling, etc.). It is a native module with its own peers - install the full set:

    npx expo install react-native-streamdown react-native-enriched-markdown remend katex
    

    It also requires react-native-worklets >= 0.8.3 (i.e. react-native-reanimated >= 4.3), and react-native-enriched-markdown is a native module, so a dev build / prebuild is required (it does not work in Expo Go). 0.3 processes the markdown on a worklet runtime, which needs react-native-worklets' Bundle Mode: pass bundleMode: true and importForwarding: { moduleNames: ['remend'] } to react-native-worklets/plugin in babel.config.js, and wrap metro.config.js in getBundleModeMetroConfig from react-native-worklets/bundleMode (the example app does both). Until Bundle Mode is on, the chat keeps the built-in renderer and logs a one-time dev hint, since 0.3 throws on its first render without it. Version 0.3+ (StreamdownText) and the older Streamdown export are both recognised. The bubble's text color, size and link color are mapped onto its markdownStyle, so replies match the chat theme in light and dark. Anything in markdownProps is forwarded to StreamdownText; a markdownStyle there is merged per element over the derived one:

    <Chat
      messageTextProps={{
        markdown: true,
        markdownProps: { markdownStyle: { codeBlock: { backgroundColor: '#0d1117' } } },
      }}
      {...props}
    />
    

Emoji Reactions

Long-press a message to open a quick emoji picker; selected reactions render as pills in the bubble and toggle on tap. The bar's chevron opens the built-in full emoji grid (search, tabs, recents) in place; both ship in the core with no extra dependencies, and renderExpandedPicker / renderReactionPicker replace them.

Long-press menu with the quick reactions bar    A reaction pill under the message    The expanded reactions grid with search and tabs

Wiring up the toggle, and the full prop list

Store reactions on each message as a reactions array and pass reactions.onReactionPress - that alone turns reactions on. Chat.toggleReaction(messages, messageId, emoji, userId) is the reducer, so the handler is one line. Reaction state is owned by you, so it works with any backend:

interface IChatMessage extends IMessage {
  reactions?: MessageReaction[] // { emoji: string, userIds: (string | number)[] }[]
}

const CURRENT_USER_ID = 1

const handleReactionPress = useCallback((message: IChatMessage, emoji: string) => {
  setMessages(prev => Chat.toggleReaction(prev, message._id, emoji, CURRENT_USER_ID))
}, [])

<Chat
  messages={messages}
  onSend={onSend}
  user={{ _id: CURRENT_USER_ID }}
  reactions={{
    onReactionPress: handleReactionPress,
    // Optional: provide a richer picker (e.g. a full emoji browser).
    // See example/components/chat-examples/ReactionsExample.tsx
    // renderReactionPicker: props => <MyEmojiPicker {...props} />,
  }}
/>

Chat.toggleReaction (also exported as toggleReaction) returns a new array and leaves other messages untouched. A user can leave up to three different reactions on a message by default, as in Telegram - a fourth replaces their oldest; pass { maxPerUser: 1 } as a fifth argument for one reaction each, or any other limit (Infinity for none).

For a prototype, useChatMessages({ initialMessages, user }) keeps the messages in local state and returns chatProps wired to sending, reactions, editing and deleting: <Chat {...chatProps} />.

Reactions Props (Grouped)

  • isEnabled (Bool) - Enable emoji reactions; default is on whenever onReactionPress is passed
  • emojis (String[]) - Emojis shown in the quick picker (default ['👍', '❤️', '😂', '😮', '😢', '👎'])
  • onReactionPress (Function) - (message, emoji) => void called when an emoji is selected or a pill is tapped. Apply it with Chat.toggleReaction
  • getUser (Function) - (userId) => User | undefined, who reacted. As in Telegram, a pill shows up to three reactors' avatars instead of a count in a one-to-one chat, and in a group while the message has three reactions or fewer, when every reactor is known. Defaults to the senders of the loaded messages (and you)
  • renderReactions (Function) - Override the reactions-display component rendered below the bubble
  • renderReactionPicker (Function) - Override the picker shown on long-press (use for a full emoji browser). It receives ReactionPickerProps: visible, message, emojis, onSelect, onDismiss, position, the bubble's on-screen box (pageX, pageY, bubbleWidth, bubbleHeight), the two picker styles and:
    • messagePreview (ReactNode, optional) - A copy of the pressed bubble to draw lifted above your backdrop at the bubble's box. While it is mounted the original bubble is hidden, so the message seems to rise out of the list; if you never render it, the original simply stays put. The easiest way to get the built-in look is to render the exported ContextMenu with items={[]} (see Message actions for its props)
  • renderExpandedPicker (Function({ onSelect }) | null, optional) - The expand button. The reactions bar (in the quick picker and above the context menu) ends in a chevron that grows the bar in place into a panel holding what this returns. Defaults to the built-in emoji grid (8 columns, search, tabs, recents); pass your own, or null to drop the button. Call onSelect(emoji) with the pick; the overlay closes and onReactionPress is called. Also passed to a custom renderReactionPicker
  • containerStyle, reactionStyle, reactionActiveStyle, reactionTextStyle, reactionCountStyle - Styles for the reaction pills
  • pickerContainerStyle, pickerEmojiStyle - Styles for the quick picker

Smart Link Parsing

URLs, emails, phones, hashtags and mentions

Message text is automatically scanned for URLs, emails, and phone numbers; hashtags and mentions are opt-in. Configure it via messageTextProps:

<Chat
  messageTextProps={{
    url: true,        // default true
    email: true,      // default true
    phone: true,      // default true
    hashtag: true,    // default false
    mention: true,    // default false
    hashtagUrl: 'https://example.com/hashtag',
    mentionUrl: 'https://example.com',
    linkStyle: { left: { color: '#1d9bf0' }, right: { color: '#fff' } },
    onPress: (message, url, type) => {
      // type: 'url' | 'email' | 'phone' | 'mention' | 'hashtag'
      Linking.openURL(url)
    },
  }}
/>

For full control, pass custom matchers ({ type, pattern, getLinkUrl?, getLinkText?, renderLink?, onPress? }[]) to add or override patterns. See the Links example in the example app.

Message actions (long-press context menu)

Floating menu

Long-press a message to open a context menu beside your finger. It opens by default with these actions: Reply, Copy (with expo-clipboard or @react-native-clipboard/clipboard installed), Forward, Pin / Unpin, Edit (your own text messages), Select and Delete - Forward, Pin, Edit and Delete appear once you pass onForwardMessage, onPinMessage, onEditMessage and onDeleteMessage. Select starts multi-select: check circles beside the messages and a Copy / Forward / Delete bar in the composer's place (see onSelectionChange). When reactions are enabled, a reactions row is shown on top of the menu automatically.

<Chat
  messages={messages}
  onSend={onSend}
  user={user}
  onEditMessage={(message, text) => setMessages(prev => prev.map(m => m._id === message._id ? { ...m, text } : m))}
  onDeleteMessage={message => setMessages(prev => prev.filter(m => m._id !== message._id))}
/>

To change the set, pass messageActions. A function receives the built-in actions for the message (each with its key), so you can add, drop or reorder; an array replaces them. defaultMessageActions picks the built-ins by key, or turns them off with false.

<Chat
  messageActions={(message, defaults) => [
    ...defaults.filter(action => action.key !== 'forward'),
    { label: 'Report', icon: ({ color, size }) => <Flag color={color} size={size} />, onPress: () => report(message) },
  ]}
/>

After 0.4s the menu opens with a haptic (if expo-haptics is installed). The message neither shrinks nor lifts - the chat dims under a black 0.2 scrim and the pressed message stays lit where it is. The menu - a 200-wide card of 48pt rows with icons, in theme.contextMenu colors - opens with its right edge just left of your finger and its top at it, unrolling from the top while each row drops into place. The reactions bar above it pops out from its right end with a slight overshoot, with a "thought bubble" tail; reactions you already picked sit smaller in a circle, and the chevron at its end grows the bar into the emoji panel. A picked reaction grows and flies into the message's reaction pill; an action runs once the menu has closed; a tap on the backdrop closes it all. Every animation runs on Reanimated and follows the system Reduce Motion setting. The reaction-only picker (reactions without messageActions) is the same overlay without actions.

A fully custom menu - each item is { key?, label, icon?, onPress, destructive? }:

import { setStringAsync } from 'expo-clipboard'
import { Copy, Trash2 } from 'lucide-react-native' // optional icons

<Chat
  messageActions={message => [
    { label: 'Copy', icon: ({ color, size }) => <Copy color={color} size={size} />, onPress: () => setStringAsync(message.text) },
    { label: 'Delete', icon: ({ color, size }) => <Trash2 color={color} size={size} />, destructive: true, onPress: () => deleteMessage(message) },
  ]}
/>

ContextMenu is exported for custom pickers and menus. Beyond visible, items, onDismiss (called once its exit has played), position and the bubble's box (pageX, pageY, bubbleWidth, bubbleHeight), it takes these optional props:

  • reactions (Object) - { emojis, onSelect, selected?, containerStyle?, emojiStyle?, renderAccessory?, renderExpandedPicker? }. selected lists the reactions the user already picked (drawn smaller, in a circle); renderAccessory adds content at the end of the bar; renderExpandedPicker adds the expand button and the panel it opens (see reactions.renderExpandedPicker above)
  • touchX, touchY (Number) - Where the finger was, in window coordinates; the menu opens beside it (beside the bubble's middle without them)
  • messagePreview (ReactNode) - The copy of the message drawn above the scrim in place; pass the one a custom picker receives
  • children (ReactNode) - Drawn above everything else in the overlay, e.g. a full emoji sheet

Note: This library no longer depends on @expo/react-native-action-sheet. Prefer messageActions above. If you specifically want a native action sheet, install it yourself, wrap your tree in ActionSheetProvider, and either call useActionSheet() in your own onLongPressMessage or pass an actionSheet prop - the actionSheet prop / context.actionSheet() escape hatch still works when you provide an implementation. The composer "+" actions use the built-in themed AttachmentSheet and need no setup.

Interactive content inside bubbles (video players, maps)

Keeping native controls tappable

When reactions or messageActions are enabled, the long-press surface spans the whole message row - the bubble and the empty space beside it. (A tap gesture is added on top only when onPressMessage is set.) Those recognizers do not cancel touches on native subviews, so a react-native-video / expo-video player rendered through renderMessageVideo keeps its native controls interactive.

If a message must own every touch that lands on it, set isMessageGestureEnabled to false for it. The gesture surface then drops behind the bubble: the bubble's content takes its touches, and long-pressing the row next to the bubble still opens the picker - so reactions are never lost for that message.

<Chat
  reactions={{ isEnabled: true, onReactionPress }}
  renderMessageVideo={props => <Video source={{ uri: props.currentMessage.video }} controls style={styles.video} />}
  // the video owns its controls; long-press beside the bubble still reacts
  isMessageGestureEnabled={message => !message.video}
/>

Theming & Dark Mode

Token groups, runtime switching and themed components

The default look is a modern messenger style: a classic day theme (pale green outgoing bubbles over a green swirl wallpaper) and a dark blue night theme (a purple-to-blue outgoing gradient fixed to the screen). Every value is a token. Override any subset via theme (light) and darkTheme (dark); your overrides are deep-merged over defaultLightTheme / defaultDarkTheme, and the resolved theme switches at runtime with the color scheme (system, or forced via colorScheme). Explicit per-component style props still win over the theme.

<Chat
  theme={{
    colors: { accent: '#3390EC', outgoingBubble: '#3390EC', outgoingText: '#FFFFFF' },
    radii: { bubble: 18 },
    wallpaper: { colors: ['#7FA381', '#FFF5C5', '#336F55', '#FBE37D'] },
  }}
  darkTheme={{ bubble: { outgoingGradient: ['#5B3FA8', '#2F6FD6'] } }}
  // colorScheme="dark"   // optional: force a scheme instead of following the system
  {...props}
/>

Token groups: colors, radii, spacing, typography, avatar, sendButton, composer, voice, plus:

  • bubble - hasTail (a curled tail on the last bubble of a run; drawn with react-native-svg when installed), isTimeInline (the time on the last line of text when it fits; false gives it a row), outgoingGradient (stops, top to bottom, or null for the solid colors.outgoingBubble), outgoingGradientMode ('screen': one gradient across the list, each bubble shows its slice as it scrolls; 'bubble': each bubble carries the whole gradient), maxWidthInset (the text column is min(width, height) - maxWidthInset, 80 by default), bigEmojiMaxCount (a message of up to this many emoji and nothing else drops its bubble and draws them large, with the time in a service pill; 20 by default, 0 turns it off), bigEmojiSizes (font size by emoji count, 40.8, 40.8, 33.6, 26.4, 22.8).
  • wallpaper - isEnabled, colors (three or four, for the swirl gradient), isAnimated (one step per outgoing message), pattern (an image tiled over the gradient; no pattern is bundled), patternOpacity, patternColor. Off, the chat shows colors.background. Replace it entirely with the renderWallpaper prop, or draw it elsewhere with the exported ChatWallpaper component.
  • nameColors - the seven sender-name colors, picked per user id. Empty uses colors.senderName.
  • avatar.palette / avatar.paletteEnd - initials avatar gradient stops, picked per user id. An empty paletteEnd draws flat colors.
  • textScale - the text size the user picked, a multiplier of every typography size (1 by default): messages, times, names, day and service pills, quotes and the composer grow together, e.g. theme={{ textScale: 1.2 }}.
  • chatList.headerSubtitle / chatList.headerSubtitleActive - ChatHeader's status line, grey and in the accent color.

A few behaviours follow from the tokens: setting colors.outgoingBubble turns the gradient off, setting colors.senderName empties nameColors, and setting avatar.palette without paletteEnd draws flat avatars - so an app that picks its own colors keeps seeing them. Bubbles in a run (same sender, at most five minutes apart, utils.isSameGroup) share one tail and one name, 2pt apart (spacing.withinGroup), with 6pt between runs (spacing.betweenGroups).

Build your own theme-aware components with the exported hooks:

import { useTheme, useThemedStyles } from '@kesha-antonov/react-native-chat'
import { StyleSheet } from 'react-native'

const MyBadge = () => {
  const theme = useTheme()
  const styles = useThemedStyles(t => StyleSheet.create({
    badge: { backgroundColor: t.colors.accent, borderRadius: t.radii.bubble },
  }))
  return <View style={styles.badge} />
}

Also exported: defaultLightTheme, defaultDarkTheme, ChatWallpaper, and the ChatTheme / PartialChatTheme types.

The built-in panels have their own token groups: emojiKeyboard, contextMenu, attachments and chatList. The full set of tokens and their default values is the ChatTheme type and defaultLightTheme / defaultDarkTheme.

Localization (i18n)

Built-in translations and label overrides

All built-in UI strings (composer placeholder, send/cancel, load earlier, today, voice/video/location labels, slide-to-cancel, reply/edit banner, camera-permission text) route through a label table. Built-in translations ship for es, fr, de, ru, zh, ar, pt, ja, ko, it, tr, hi, nl, pl and id, with English as the default, selected by the existing locale prop. A regional tag falls back to its base language, so pt-BR resolves to pt. Override any individual string with labels:

<Chat
  locale="fr"                       // pick a built-in translation
  labels={{ placeholder: 'Votre message...' }}  // override any string
  {...props}
/>

Right-to-left layout follows the locale (Arabic, Hebrew, Persian, Urdu and a few others). forceRTL overrides the guess: true for an RTL language not in that set, false to keep a left-to-right layout.

Exported helpers: ChatLabels (type), defaultLabels, translations, resolveLabels, and the useLabels hook for reading the resolved labels in custom components.

Message Status

Tick indicators for sent / delivered / read

Set sent, received, pending or isFailed on a message to show its delivery status. The status is yours to set: add a message with pending: true in onSend, then set sent and received as your backend confirms. Every outgoing message shows it, voice notes, round notes, files and photos included. They render beside the time: one check once sent, two once received (read), a spinning clock while pending, a red badge when sending failed. isEdited or editedAt prefix the time with "edited":

const message: IMessage = {
  _id: 1,
  text: 'Delivered!',
  createdAt: new Date(),
  user: { _id: 1 },
  sent: true,
  received: true,
}

Customize the indicators with renderTicks (full override) or tickStyle (style only):

<Chat
  renderTicks={message => (message.received ? <MyReadIcon /> : null)}
  tickStyle={{ color: '#1d9bf0' }}
/>

TypeScript

Generic over your own message type

Chat ships complete type definitions and is generic over your message type. Extend IMessage to add custom fields and everything stays typed end to end:

import { Chat, IMessage } from '@kesha-antonov/react-native-chat'

interface MyMessage extends IMessage {
  reactions?: { emoji: string, userIds: (string | number)[] }[]
}

<Chat<MyMessage>
  messages={messages}
  onSend={msgs => {/* msgs is typed as MyMessage[] */}}
  user={{ _id: 1 }}
/>

Building blocks

Lower-level components and helpers

Chat is assembled from exported parts, so you can reuse them in your own screens or render props:

  • Rows and bubbles: Message, Bubble, MessageText, MessageImage, MessageVideo, MessageAudio, MessageFile, MessageLocation, MessageReply, SystemMessage, Day, Time, Avatar, ChatAvatar, UnreadSeparator, ChatEmpty, LinkPreviewCard, MediaCard
  • Composer: InputToolbar, Composer, Send, Actions, ReplyPreview, EmojiGrid, AttachmentMenu, AttachmentSheet
  • Voice and video: VoiceMessageInput, WaveformPlayer, VideoRecordButton, VideoNoteRecorder, with isVoiceRecordingAvailable, isWaveformAvailable, isVideoRecordingAvailable, isVisionCameraAvailable
  • Menus and status: ContextMenu, TypingStatus (getTypingText), StreamingCursor, MarkdownMessageText (isMarkdownAvailable), BasicMarkdown
  • Lists: MessagesContainer, ChatList, ChatListCell, ChatListAvatar, ChatListShimmer
  • Hooks: useTheme, useThemedStyles, useColorScheme, useIcons, useLabels, useIsRTL, useChatContext, useStreamingMessages, useChatMessages, useChatList
  • Helpers: toggleReaction, getChatCapabilities, buildAttachmentMessages, getAttachmentTabs, formatFileSize, findFirstUrl, countEmojiOnly, isRTLLocale, mirrorPosition, formatChatListDate, getChatPreview, sortChats, matchesChatQuery, DEFAULT_MESSAGE_ACTION_KEYS, EMOJI_CATEGORY_KEYS, DEFAULT_RECENT_EMOJIS

Components rendered outside Chat need a GestureHandlerRootView above them.


📱 Platform Notes

Android

Keyboard configuration

If you are using Create React Native App / Expo, no Android specific installation steps are required. Otherwise, we recommend modifying your project configuration:

Make sure you have android:windowSoftInputMode="adjustResize" in your AndroidManifest.xml:

<activity
  android:name=".MainActivity"
  android:label="@string/app_name"
  android:windowSoftInputMode="adjustResize"
  android:configChanges="keyboard|keyboardHidden|orientation|screenSize">

For Expo, you can append KeyboardAvoidingView after Chat (Android only):

<View style={{ flex: 1 }}>
   <Chat />
   {Platform.OS === 'android' && <KeyboardAvoidingView behavior="padding" />}
</View>

Web (react-native-web)

Install the web renderer alongside the library:

yarn add react-native-web react-dom
Expo / Metro (recommended) - no extra config
npx expo start --web

Nothing else to set up. Metro runs Babel over node_modules, so this package's JSX and its Reanimated worklets get transpiled the same way your own code does. The example app runs on web exactly like this.

Other bundlers (webpack, Vite, Next.js) - the package must be transpiled

The published files are ES modules with JSX left in place, and the component uses Reanimated worklets, which need react-native-reanimated/plugin to run. Bundlers that skip node_modules when transpiling - webpack's babel-loader does by default - will choke on that. So outside Metro you need to:

  1. Alias react-native to react-native-web and let the resolver pick up .web.js / .web.tsx extensions
  2. Run @kesha-antonov/react-native-chat - and the React Native packages it depends on - through Babel with @react-native/babel-preset and react-native-reanimated/plugin, instead of excluding all of node_modules

In Next.js that is transpilePackages in next.config.js; in a plain webpack setup it means widening the babel-loader rule's exclude so these packages are included.

React Strict DOM

Works inside an RSD tree - verified on iOS and Expo web

Chat drops into a React Strict DOM app unchanged. RSD's native build renders through React Native, so <Chat> is just another RN subtree:

import { css, html } from 'react-strict-dom'
import { Chat } from '@kesha-antonov/react-native-chat'

const styles = css.create({
  root: { display: 'flex', flexDirection: 'column', height: '100%' },
})

<html.div data-layoutconformance='strict' style={styles.root}>
  <Chat messages={messages} onSend={onSend} user={user} />
</html.div>

Three things to know:

  • Web needs react-native-web. RSD's web build contains no React Native code at all, so Chat does not resolve there on its own. Expo web gives you react-native-web already, so RSD (real DOM) and Chat (RNW's DOM output) render side by side in one tree. A Vite or Next.js RSD app has to add the alias and transpile step from the section above
  • Metro needs unstable_enablePackageExports: true. RSD publishes only an exports map with no main, so with package exports off it fails to resolve. This is the default on recent Expo SDKs
  • StyleX styles do not reach Chat. It takes React Native style objects and its own theme prop, not css.create output. On native, compat.native is the bridge if you want RSD to drive a wrapper around it

⚡ Performance

A message re-renders only when something it shows changes. Each row subscribes to its own message by id, so a send, a status tick, a reaction or a streamed token renders that one row (plus a neighbour only when the bubbles' grouping changes) and leaves the list and the composer alone. Everything the rows share - render props, styles, actions, labels - reaches them through context, kept stable between renders:

  • Event handlers can be inline. onPressMessage={() => ...}, reply={{ onPress: ... }}, an action's onPress: they are called through a stable proxy that always reaches your latest handler.
  • Style and config objects can be inline. timeTextStyle={{ left: { color } }}, reactions={{ isEnabled: true }} are compared by content.
  • Memoize render functions. A new renderBubble may draw something new, so a new reference re-renders every row - wrap it in useCallback.
// ✅ Handlers and objects inline; the render function memoized
const renderBubble = useCallback(props => <MyBubble {...props} />, [])

<Chat renderBubble={renderBubble} onPressMessage={message => open(message)} timeTextStyle={{ left: { color: 'gray' } }} />
Messages, neighbours, context props and virtualization tuning

Keep messages immutable. Update a message by replacing its object (e.g. Chat.append(...), or messages.map(m => m._id === id ? { ...m, sent: true } : m)), never by mutating it in place. A store that rebuilds every message object on each update still only re-renders what changed - unchanged messages are compared by content.

Neighbours are for grouping. previousMessage / nextMessage handed to renderMessage, renderBubble or renderAvatar are kept current for what decides grouping (sender, day, time apart, whether there is one). A row does not re-render because a neighbour's text, status or reactions changed, so do not draw those from a neighbour.

Theme, icons and labels don't need drilling. theme / darkTheme, icons, and labels are read from context (useTheme, useIcons, useLabels), so passing them once on <Chat> is enough; they don't cause per-row churn.

Tune virtualization if needed. The list is Legend List, which keeps only what is near the viewport mounted. drawDistance (in pixels) sets how far beyond the screen it renders; raise it if fast flings show blank space, lower it to mount less. Leave recycleItems off: message rows hold state (players, animations) that must not move to another message.

<Chat listProps={{ drawDistance: 500 }} {...props} />

🧪 Testing

Triggering layout events in tests

TEST_ID is exported as constants that can be used in your testing library of choice.

React Native Chat uses onLayout to determine the height of the chat container. To trigger onLayout during your tests:

const WIDTH = 200
const HEIGHT = 2000

const loadingWrapper = getByTestId(TEST_ID.LOADING_WRAPPER)
fireEvent(loadingWrapper, 'layout', {
  nativeEvent: {
    layout: {
      width: WIDTH,
      height: HEIGHT,
    },
  },
})

📦 Example App

Running the demo locally

The repository includes an example app with two parts. The Chats tab is a small messenger built on the defaults: a chat list (unread badges, pinned and muted chats, "typing…" previews, swipe to archive, long-press selection, a compose button) where each chat is a bare <Chat> with seeded history, and sending moves the chat to the top and gets a simulated reply. The Explore tab has one screen per feature or customization: streaming AI replies, reactions, the long-press menu, media and voice, theming, localization, links, custom rendering, a Slack-style layout, and more.

git clone https://github.com/kesha-antonov/react-native-chat.git
cd react-native-chat/example
yarn install

npx expo run:ios       # iOS
npx expo run:android   # Android
npx expo start --web   # Web

❓ Troubleshooting

"Cannot read property 'Chat' of undefined"

This means the package threw while it was being loaded, so the import came back empty. The real cause is the first error in the Metro log or red box, logged before this one - almost always a native peer that is missing or out of sync with the installed app:

  • react-native-reanimated, react-native-worklets, react-native-gesture-handler and react-native-keyboard-controller are native modules. After installing or upgrading any of them, rebuild the app (npx expo run:ios, npx expo prebuild, or pod install + a native build) - reloading the JS bundle is not enough.
  • In Expo, install them with npx expo install so the versions match your SDK. A plain npm install pulls the latest releases, which Expo Go and an existing dev build may not include, and Reanimated throws a version-mismatch error on import.
  • In bare React Native, check the worklets Babel plugin is in babel.config.js (see Bare React Native Projects), then restart Metro with --reset-cache.
The whole message list is blurred on iOS 26

The chat sits under a transparent navigation header - Expo Router 58's default is a transparent Liquid Glass header the screen scrolls under. iOS 26 then blurs scroll content beneath the header with a scroll edge effect, so the messages under the header are blurred. Give the chat screen an opaque header:

<Stack.Screen name='chat' options={{ headerTransparent: false }} />
TextInput is hidden on Android

Make sure you have android:windowSoftInputMode="adjustResize" in your AndroidManifest.xml. See Android configuration above.

How to set Bubble color for each user?

See this issue for examples.

How to customize InputToolbar styles?

See this issue for examples.

How to manually dismiss the keyboard?

See this issue for examples.

How to use renderLoading?

See this issue for examples.


🤔 Have a Question?

  1. Check this README first
  2. Search existing issues
  3. Ask on StackOverflow
  4. Open a new issue if needed

🤝 Contributing

Contributions are welcome - fork, branch, and open a Pull Request.

Development Setup

Commands
yarn install          # install dependencies
yarn build            # build the library
yarn test             # run tests
yarn lint             # run linting
yarn prepublishOnly   # full validation

Before opening a PR, please make sure yarn test, yarn lint and yarn build all pass.


👥 Authors

Based on FaridSafi/react-native-gifted-chat, which is no longer actively maintained.

Maintainer: Kesha Antonov

I also build cryptoc - a crypto portfolio app with home screen, lock screen and Watch widgets, no account and no exchange API keys.

I maintained the original project solo for 2 years before deciding to continue development in this repository. If you find this library useful, please consider becoming a sponsor to support continued development. 💖


📄 License

MIT


Built with ❤️ by the React Native community