gem-hunter
Language: TypeScript
💬 The most complete chat UI for React Native
The most complete chat UI for React Native & Web
Note
Active development has moved. This package is now in maintenance mode and isn't receiving new features. Development continues - including streaming AI messages and the latest fixes - in a maintained fork: @kesha-antonov/react-native-chat. New projects are encouraged to use it; migrating is mostly a rename (see the fork's migration guide).
|
|
|
Le Reacteur - Coding Bootcamp in Paris co-founded by Farid Safi
Stream - Scalable chat API/Server written in Go (API Tour | Tutorial)
Ethora - A complete app engine featuring GiftedChat (GitHub)
📚 React Key Concepts (2nd ed.)
| Requirement | Version |
|---|---|
| React Native | >= 0.70.0 |
| iOS | >= 13.4 |
| Android | API 21+ (Android 5.0) |
| Expo | SDK 50+ |
| TypeScript | >= 5.0 (optional) |
npx expo install react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
Step 1: Install the packages
Using yarn:
yarn add react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
Using npm:
npm install --save react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
Step 2: Install iOS pods
npx pod-install
Step 3: Configure react-native-reanimated
Follow the react-native-reanimated installation guide to add the Babel plugin.
import React, { useState, useCallback, useEffect } from 'react' import { GiftedChat } from 'react-native-gifted-chat' import { useHeaderHeight } from '@react-navigation/elements' export function Example() { const [messages, setMessages] = useState([]) // keyboardVerticalOffset = distance from screen top to GiftedChat container // useHeaderHeight() returns status bar + navigation header height const headerHeight = useHeaderHeight() useEffect(() => { setMessages([ { _id: 1, text: 'Hello developer', createdAt: new Date(), user: { _id: 2, name: 'John Doe', avatar: 'https://placeimg.com/140/140/any', }, }, ]) }, []) const onSend = useCallback((messages = []) => { setMessages(previousMessages => GiftedChat.append(previousMessages, messages), ) }, []) return ( <GiftedChat messages={messages} onSend={messages => onSend(messages)} user={{ _id: 1, }} keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight }} /> ) }
💡 Tip: Check out more examples in the
exampledirectory including Slack-style messages, quick replies, and custom components.
Messages, system messages, and quick replies follow the structure defined in Models.ts.
Message Object Structureinterface IMessage { _id: string | number text: string createdAt: Date | number user: User image?: string video?: string audio?: string system?: boolean sent?: boolean received?: boolean pending?: boolean quickReplies?: QuickReplies } interface User { _id: string | number name?: string avatar?: string | number | (() => React.ReactNode) }
messages (Array) - Messages to displayuser (Object) - User sending the messages: { _id, name, avatar }onSend (Function) - Callback when sending a messagemessageIdGenerator (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.messagesContainerRef (FlatList ref) - Ref to the flatlisttextInputRef (TextInput ref) - Ref to the text inputkeyboardProviderProps (Object) - Props to be passed to the KeyboardProvider for keyboard handling. Default values:
statusBarTranslucent: true - Required on Android for correct keyboard height calculation when status bar is translucent (edge-to-edge mode)navigationBarTranslucent: true - Required on Android for correct keyboard height calculation when navigation bar is translucent (edge-to-edge mode)disableKeyboardProvider (Bool) - Skip rendering the built-in KeyboardProvider wrapper; default is false. Enable this when your app already mounts its own KeyboardProvider (e.g. once at the root), or when the default edge-to-edge behavior causes a layout shift, flicker on mount, or a header/content jump on Android/Expo. See Using your own KeyboardProvider below.keyboardAvoidingViewProps (Object) - Props to be passed to the KeyboardAvoidingView. See keyboardVerticalOffset below for proper keyboard handling.isAlignedTop (Boolean) Controls whether or not the message bubbles appear at the top of the chat (Default is false - bubbles align to bottom)isInverted (Bool) - Reverses display order of messages; default is trueThe keyboardVerticalOffset tells the KeyboardAvoidingView where its container starts relative to the top of the screen. This is essential when GiftedChat is not positioned at the very top of the screen (e.g., when you have a navigation header).
Default value: insets.top (status bar height from useSafeAreaInsets()). This works correctly only when GiftedChat fills the entire screen without a navigation header. If you have a navigation header, you need to pass the correct offset via keyboardAvoidingViewProps.
What the value means: The offset equals the distance (in points) from the top of the screen to the top of your GiftedChat container. This typically includes:
useHeaderHeight() already includes status bar)How to use:
import { useHeaderHeight } from '@react-navigation/elements' function ChatScreen() { // useHeaderHeight() returns status bar + navigation header height on iOS const headerHeight = useHeaderHeight() return ( <GiftedChat keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight }} // ... other props /> ) }
Note:
useHeaderHeight()requires your chat component to be rendered inside a proper navigation screen (not conditional rendering). If it returns0, ensure your chat screen is a real navigation screen with a visible header.
Why this matters: Without the correct offset, the keyboard may overlap the input field or leave extra space. The KeyboardAvoidingView uses this value to calculate how much to shift the content when the keyboard appears.
By default GiftedChat wraps itself in a KeyboardProvider with statusBarTranslucent and navigationBarTranslucent enabled. On some Android/Expo (edge-to-edge) setups this can cause the screen to shift down, flicker on mount, or distort a navigation header - especially when another KeyboardProvider already exists higher in the tree.
Set disableKeyboardProvider to skip the built-in wrapper:
import { KeyboardProvider } from 'react-native-keyboard-controller' // Mount a single KeyboardProvider once, near the root of your app function App() { return ( <KeyboardProvider> {/* ...navigation / screens... */} </KeyboardProvider> ) } function ChatScreen() { return ( <GiftedChat disableKeyboardProvider // ... other props /> ) }
Important: GiftedChat's keyboard avoidance relies on a
KeyboardProviderbeing present in the tree. When you setdisableKeyboardProvider, you must mount your ownKeyboardProviderabove GiftedChat - otherwise the keyboard will cover the input. Mounting exactly one provider (yours) is what avoids the double edge-to-edge shift.
text (String) - Input text; default is undefined, but if specified, it will override GiftedChat's internal state. Useful for managing text state outside of GiftedChat (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 fieldisSendButtonAlwaysVisible (Bool) - Always show send button in input text composer; default false, show only when text input is not emptyisTextOptional (Bool) - Allow sending messages without text (useful for media-only messages); default false. Use with isSendButtonAlwaysVisible for media attachments.minComposerHeight (Object) - Custom min-height of the composer.maxComposerHeight (Object) - Custom max height of the composer.minInputToolbarHeight (Integer) - Minimum height of the input toolbar; default is 44renderInputToolbar (Component | Function) - Custom message composer containerrenderComposer (Component | Function) - Custom text input message composerrenderSend (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 composerrenderAccessory (Component | Function) - Custom second line of actions below the message composertextInputProps (Object) - props to be passed to the <TextInput>.onPressActionButton (Function) - Callback when the Action button is pressed (if set, the default actionSheet will not be used)actionSheet (Function) - Custom action sheet interface for showing action optionsactions (Array) - Custom action options for the input toolbar action button; array of objects with title (string) and action (function) propertiesactionSheetOptionTintColor (String) - Tint color for action sheet optionsmessagesContainerStyle (Object) - Custom style for the messages containerrenderMessage (Component | Function) - Custom message containerrenderLoading (Component | Function) - Render a loading view when initializingrenderChatEmpty (Component | Function) - Custom component to render in the ListView when messages are emptyrenderChatFooter (Component | Function) - Custom component to render below the MessagesContainer (separate from the ListView)listProps (Object) - Extra props to be passed to the messages <FlatList>. Supports all FlatList props including maintainVisibleContentPosition for keeping scroll position when new messages arrive (useful for AI chatbots).renderBubble (Component | Function(props: BubbleProps)) - Custom message bubble. Receives BubbleProps as parameter.renderMessageText (Component | Function) - Custom message textrenderMessageImage (Component | Function) - Custom message imagerenderMessageVideo (Component | Function) - Custom message videorenderMessageAudio (Component | Function) - Custom message audiorenderCustomView (Component | Function) - Custom view inside the bubbleisCustomViewBottom (Bool) - Determine whether renderCustomView is displayed before or after the text, image and video views; default is falseonPressMessage (Function(context, message)) - Callback when a message bubble is pressedonLongPressMessage (Function(context, message)) - Callback when a message bubble is long-pressed; you can use this to show action sheets (e.g., copy, delete, reply)imageProps (Object) - Extra props to be passed to the <Image> component created by the default renderMessageImageimageStyle (Object) - Custom style for message imagesvideoProps (Object) - Extra props to be passed to the video component created by the required renderMessageVideomessageTextProps (Object) - Extra props to be passed to the MessageText component. Useful for customizing link parsing behavior, text styles, and matchers. Supports the following props:
matchers - Custom matchers for linking message content (like URLs, phone numbers, hashtags, mentions)linkStyle - Custom style for linksemail - Enable/disable email parsing (default: true)phone - Enable/disable phone number parsing (default: true)url - Enable/disable URL parsing (default: true)hashtag - Enable/disable hashtag parsing (default: false)mention - Enable/disable mention parsing (default: false)hashtagUrl - Base URL for hashtags (e.g., 'https://x.com/hashtag')mentionUrl - Base URL for mentions (e.g., 'https://x.com')stripPrefix - Strip 'http://' or 'https://' from URL display (default: false)TextComponent - Custom Text component to use (e.g., from react-native-gesture-handler)Example:
<GiftedChat 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 full example in LinksExample
renderAvatar (Component | Function) - Custom message avatar; set to null to not render any avatar for the messageisUserAvatarVisible (Bool) - Whether to render an avatar for the current user; default is false, only show avatars for other usersisAvatarVisibleForEveryMessage (Bool) - When false, avatars will only be displayed when a consecutive message is from the same user on the same day; default is falseonPressAvatar (Function(user)) - Callback when a message avatar is tappedonLongPressAvatar (Function(user)) - Callback when a message avatar is long-pressedisAvatarOnTop (Bool) - Render the message avatar at the top of consecutive messages, rather than the bottom; default is falseisUsernameVisible (Bool) - Indicate whether to show the user's username inside the message bubble; default is falserenderUsername (Component | Function) - Custom Username containertimeFormat (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. The same function renders both the inline day separators and the floating/animated day header that sticks to the top while scrolling. Read props.isAnimated (true for the floating header, false for the inline separator) to give each a different look.dayProps (Object) - Props to pass to the Day component:
containerStyle - Custom style for the day containerwrapperStyle - Custom style for the day wrappertextProps - Props to pass to the Text component (e.g., style, allowFontScaling, numberOfLines)renderTime (Component | Function) - Custom time inside a messagetimeTextStyle (Object) - Custom text style for time inside messages (supports left/right styles)isDayAnimationEnabled (Bool) - Enable animated day label that appears on scroll; default is truerenderSystemMessage (Component | Function) - Custom system messageloadEarlierMessagesProps (Object) - Props to pass to the LoadEarlierMessages component. The button is only visible when isAvailable is true. Supports the following props:
isAvailable - Controls button visibility (default: false)onPress - Callback when button is pressedisLoading - Display loading indicator (default: false)isInfiniteScrollEnabled - Enable infinite scroll up when reaching the top of messages container, automatically calls onPress (not yet supported for web)label - Override the default "Load earlier messages" textcontainerStyle - Custom style for the button containerwrapperStyle - Custom style for the button wrappertextStyle - Custom style for the button textactivityIndicatorStyle - Custom style for the loading indicatoractivityIndicatorColor - Color of the loading indicator (default: 'white')activityIndicatorSize - Size of the loading indicator (default: 'small')renderLoadEarlier (Component | Function) - Custom "Load earlier messages" buttonisTyping (Bool) - Typing Indicator state; default false. If you userenderFooter it will override this.renderTypingIndicator (Component | Function) - Custom typing indicator componenttypingIndicatorStyle (StyleProp) - Custom style for the TypingIndicator component.renderFooter (Component | Function) - Custom footer component on the ListView, e.g. 'User is typing...'; see CustomizedFeaturesExample.tsx for an example. Overrides default typing indicator that triggers when isTyping is true.See Quick Replies example in messages.ts
onQuickReply (Function) - Callback when sending a quick reply (to backend server)renderQuickReplies (Function) - Custom all quick reply viewquickReplyStyle (StyleProp) - Custom quick reply view stylequickReplyTextStyle (StyleProp) - Custom text style for quick reply buttonsquickReplyContainerStyle (StyleProp) - Custom container style for quick repliesrenderQuickReplySend (Function) - Custom quick reply send viewGifted Chat supports swipe-to-reply functionality out of the box. When enabled, users can swipe on a message to reply to it, displaying a reply preview in the input toolbar and the replied message above the new message bubble.
Note: This feature uses
ReanimatedSwipeablefromreact-native-gesture-handlerandreact-native-reanimatedfor smooth, performant animations.
<GiftedChat messages={messages} onSend={onSend} user={{ _id: 1 }} reply={{ swipe: { isEnabled: true, direction: 'left', // swipe left to reply }, }} />
The reply prop accepts an object with the following structure:
interface ReplyProps<TMessage> { // Swipe gesture configuration swipe?: { isEnabled?: boolean // Enable swipe-to-reply; default false 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: TMessage) => void // Called when reply preview tapped // Custom renderers renderPreview?: (props: ReplyPreviewProps) => React.ReactNode renderMessageReply?: (props: MessageReplyProps) => React.ReactNode }
When a message has a reply, it includes a replyMessage property:
interface ReplyMessage { _id: string | number text: string user: User image?: string audio?: string }
const [replyMessage, setReplyMessage] = useState<ReplyMessage | null>(null) <GiftedChat messages={messages} onSend={messages => { const newMessages = messages.map(msg => ({ ...msg, replyMessage: replyMessage || undefined, })) setMessages(prev => GiftedChat.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), }} />
The reply preview automatically animates when:
These animations use react-native-reanimated for 60fps performance.
isScrollToBottomEnabled (Bool) - Enables the scroll to bottom Component (Default is false)scrollToBottomComponent (Function) - Custom Scroll To Bottom Component containerscrollToBottomOffset (Integer) - Custom Height Offset upon which to begin showing Scroll To Bottom Component (Default is 200)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.)For AI chat interfaces where long responses arrive and you don't want to disrupt the user's reading position, use maintainVisibleContentPosition via listProps:
// Basic usage - always maintain scroll position <GiftedChat listProps={{ maintainVisibleContentPosition: { minIndexForVisible: 0, }, }} /> // With auto-scroll threshold - auto-scroll if within 10 pixels of newest content <GiftedChat listProps={{ maintainVisibleContentPosition: { minIndexForVisible: 0, autoscrollToTopThreshold: 10, }, }} /> // Conditionally enable based on scroll state (recommended for chatbots) const [isScrolledUp, setIsScrolledUp] = useState(false) <GiftedChat listProps={{ onScroll: (event) => { setIsScrolledUp(event.contentOffset.y > 50) }, maintainVisibleContentPosition: isScrolledUp ? { minIndexForVisible: 0, autoscrollToTopThreshold: 10 } : undefined, }} />
Long-press a message to open a quick emoji picker; selected reactions render as pills below the bubble and toggle on tap. The core ships a lightweight quick picker (built on react-native-gesture-handler and react-native-reanimated, no extra dependencies). A full emoji browser is optional and demonstrated in the example app via the renderReactionPicker override.
Store reactions on each message as a reactions array, then enable the feature and handle the toggle. 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 => prev.map(m => { if (m._id !== message._id) return m const existing = (m.reactions ?? []).find(r => r.emoji === emoji) if (!existing) return { ...m, reactions: [...(m.reactions ?? []), { emoji, userIds: [CURRENT_USER_ID] }] } const userIds = existing.userIds.includes(CURRENT_USER_ID) ? existing.userIds.filter(id => id !== CURRENT_USER_ID) : [...existing.userIds, CURRENT_USER_ID] return { ...m, reactions: userIds.length === 0 ? (m.reactions ?? []).filter(r => r.emoji !== emoji) : (m.reactions ?? []).map(r => (r.emoji === emoji ? { ...r, userIds } : r)), } }) ) }, []) <GiftedChat messages={messages} onSend={onSend} user={{ _id: CURRENT_USER_ID }} reactions={{ isEnabled: true, onReactionPress: handleReactionPress, // Optional: provide a richer picker (e.g. a full emoji browser). // See example/components/chat-examples/ReactionsExample.tsx // renderReactionPicker: props => <MyEmojiPicker {...props} />, }} />
The reactions prop accepts:
isEnabled (Bool) - Enable emoji reactions (default false)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. Toggle logic is left to yourenderReactions (Function) - Override the reactions-display component rendered below the bubblerenderReactionPicker (Function) - Override the picker shown on long-press (use for a full emoji browser)containerStyle, reactionStyle, reactionActiveStyle, reactionTextStyle, reactionCountStyle - Styles for the reaction pillspickerContainerStyle, pickerEmojiStyle - Styles for the quick pickerMessage text is automatically scanned for URLs, emails, and phone numbers; hashtags and mentions are opt-in. Configure it via messageTextProps:
<GiftedChat 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.
Long-press handling is exposed via onLongPressMessage. GiftedChat wraps @expo/react-native-action-sheet, so you can show a "Copy Text" action sheet and copy with the clipboard library of your choice:
import { useActionSheet } from '@expo/react-native-action-sheet' import { setStringAsync } from 'expo-clipboard' const { showActionSheetWithOptions } = useActionSheet() <GiftedChat onLongPressMessage={(_context, message) => { showActionSheetWithOptions( { options: ['Copy Text', 'Cancel'], cancelButtonIndex: 1 }, buttonIndex => { if (buttonIndex === 0) setStringAsync(message.text) } ) }} />
Set sent, received, or pending on a message to show its delivery status. By default these render as tick indicators next to the timestamp (✓ sent, ✓✓ received, 🕓 pending):
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):
<GiftedChat renderTicks={message => (message.received ? <MyReadIcon /> : null)} tickStyle={{ color: '#1d9bf0' }} />
GiftedChat 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 { GiftedChat, IMessage } from 'react-native-gifted-chat' interface MyMessage extends IMessage { reactions?: { emoji: string, userIds: (string | number)[] }[] } <GiftedChat<MyMessage> messages={messages} onSend={msgs => {/* msgs is typed as MyMessage[] */}} user={