react-native-gifted-chat 3.2.3 → 3.3.2

package/README.md

@@ -1,33 +1,45 @@
-<h3 align="center">
-  💬 Gifted Chat
-</h3>
 <p align="center">
-  The most complete chat UI for React Native & Web
-</p>
-<p align="center">
-  <a href="https://www.npmjs.com/package/react-native-gifted-chat">
-  <img alt="npm downloads" src="https://img.shields.io/npm/dm/react-native-gifted-chat.svg"/></a>
   <a href="https://www.npmjs.com/package/react-native-gifted-chat"><img alt="npm version" src="https://badge.fury.io/js/react-native-gifted-chat.svg"/></a>
-  <a href="https://circleci.com/gh/FaridSafi/react-native-gifted-chat"><img src="https://circleci.com/gh/FaridSafi/react-native-gifted-chat.svg?style=shield" alt="build"></a>
+  <a href="https://www.npmjs.com/package/react-native-gifted-chat"><img alt="npm downloads" src="https://img.shields.io/npm/dm/react-native-gifted-chat.svg"/></a>
+  <a href="https://circleci.com/gh/FaridSafi/react-native-gifted-chat"><img src="https://circleci.com/gh/FaridSafi/react-native-gifted-chat.svg?style=shield" alt="build"></a>
+  <img src="https://img.shields.io/badge/platforms-iOS%20%7C%20Android%20%7C%20Web-lightgrey.svg" alt="platforms">
+  <img src="https://img.shields.io/badge/TypeScript-supported-blue.svg" alt="TypeScript">
+  <img src="https://img.shields.io/badge/Expo-compatible-000020.svg" alt="Expo compatible">
 </p>
 
----
+<h1 align="center">React Native Gifted Chat</h1>
 
-<h3 align="center">
-  🚀 Try it now in your browser!
-</h3>
 <p align="center">
-  <a href="https://snack.expo.dev/@kesha-antonov/gifted-chat-playground" target="_blank">
-    <img src="https://img.shields.io/badge/▶️_Try_GiftedChat_Playground-4630EB?style=for-the-badge&logo=expo&logoColor=white" alt="Try GiftedChat on Expo Snack"/>
-  </a>
+  The most complete chat UI for React Native & Web
 </p>
+
 <p align="center">
-  <strong>No installation required • Interactive examples • Edit and run in real-time</strong>
+  <a href="https://snack.expo.dev/@kesha-antonov/gifted-chat-playground" target="_blank">
+    <img src="https://img.shields.io/badge/▶️_Try_in_Browser-4630EB?style=for-the-badge&logo=expo&logoColor=white" alt="Try GiftedChat on Expo Snack"/>
+  </a>
 </p>
 
-<br />
+---
 
-<!-- previews -->
+## ✨ Features
+
+- 🎨 **Fully Customizable** - Override any component with your own implementation
+- 📎 **Composer Actions** - Attach photos, files, or trigger custom actions
+- ↩️ **Reply to Messages** - Swipe-to-reply with reply preview and message threading
+- ⏮️ **Load Earlier Messages** - Infinite scroll with pagination support
+- 📋 **Copy to Clipboard** - Long-press messages to copy text
+- 🔗 **Smart Link Parsing** - Auto-detect URLs, emails, phone numbers, hashtags, mentions
+- 👤 **Avatars** - User initials or custom avatar images
+- 🌍 **Localized Dates** - Full i18n support via Day.js
+- ⌨️ **Keyboard Handling** - Smart keyboard avoidance for all platforms
+- 💬 **System Messages** - Display system notifications in chat
+- ⚡ **Quick Replies** - Bot-style quick reply buttons
+- ✍️ **Typing Indicator** - Show when users are typing
+- ✅ **Message Status** - Tick indicators for sent/delivered/read states
+- ⬇️ **Scroll to Bottom** - Quick navigation button
+- 🌐 **Web Support** - Works with react-native-web
+- 📱 **Expo Support** - Easy integration with Expo projects
+- 📝 **TypeScript** - Complete TypeScript definitions included
 
 <p align="center">
   <img width="200" src="https://github.com/user-attachments/assets/c9da88f5-0b20-471c-8cd7-373bdb767517" />
@@ -39,124 +51,84 @@
 
 ---
 
-## Features
-
-- Fully customizable components
-- Composer actions (to attach photos, etc.)
-- Load earlier messages
-- Copy messages to clipboard
-- Touchable links with customizable parsing (URLs, emails, phone numbers, hashtags, mentions)
-- Avatar as user's initials
-- Localized dates
-- Multi-line TextInput
-- InputToolbar avoiding keyboard
-- System message
-- Quick Reply messages (bot)
-- Typing indicator
-- Ticks indicator to display message status ( delivered, read )
-- Scroll to bottom button
-- react-native-web [web configuration](#react-native-web)
-
-## Sponsor
+## 📖 Table of Contents
+
+- [Features](#-features)
+- [Requirements](#-requirements)
+- [Installation](#-installation)
+- [Usage](#-usage)
+- [Props Reference](#-props-reference)
+- [Data Structure](#-data-structure)
+- [Platform Notes](#-platform-notes)
+- [Example App](#-example-app)
+- [Troubleshooting](#-troubleshooting)
+- [Contributing](#-contributing)
+- [Authors](#-authors)
+- [License](#-license)
 
-<p align="center">
-  <br/>
-  <a href="https://www.lereacteur.io" target="_blank">
-    <img src="https://raw.githubusercontent.com/FaridSafi/react-native-gifted-chat/master/media/logo_sponsor.png" height="60">
-  </a>
-  <br>
-  <p align="center">
-    Coding Bootcamp in Paris co-founded by Farid Safi
-  </p>
-  <a href="https://www.lereacteur.io" target="_blank">
-    <p align="center">
-      Click to learn more
-    </p>
-  </a>
-</p>
+---
 
-<p align="center">
-  <br/>
-  <a href="https://getstream.io/chat/?utm_source=Github&utm_medium=Github_Repo_Content_Ad&utm_content=Developer&utm_campaign=Github_Jan2022_Chat&utm_term=react-native-gifted-chat" target="_blank">
-    <img src="https://raw.githubusercontent.com/FaridSafi/react-native-gifted-chat/master/media/stream-logo.png" height="40">
-  </a>
-  <br>
-  <p align="center">
-    Scalable <a href="https://getstream.io/chat/?utm_source=Github&utm_medium=Github_Repo_Content_Ad&utm_content=Developer&utm_campaign=Github_Jan2022_Chat&utm_term=react-native-gifted-chat" target="_blank">chat API/Server</a> written in Go
-  </p>
-  <p align="center">
-    <a href="https://getstream.io/chat/get_started/?utm_source=Github&utm_medium=Github_Repo_Content_Ad&utm_content=Developer&utm_campaign=Github_Jan2022_Chat&utm_term=react-native-gifted-chat" target="_blank">API Tour</a> | <a href="https://dev.to/nickparsons/react-native-chat-with-chuck-norris-3h7m?utm_source=Github&utm_medium=Github_Repo_Content_Ad&utm_content=Developer&utm_campaign=Github_Jan2022_Chat&utm_term=react-native-gifted-chat" target="_blank">React Native Gifted tutorial</a>
-  </p>
-</p>
+## 📋 Requirements
 
-<p align="center">
-  <br/>
-  <a href="https://www.ethora.com" target="_blank">
-    <img src="https://www.dappros.com/wp-content/uploads/2023/12/Ethora-Logo.png" height="60">
-  </a>
-  <br>
-  <p align="center">
-    A complete app engine featuring GiftedChat
-  </p>
-  <p align="center">
-    <a href="https://bit.ly/ethorachat" target="_blank">Check out our GitHub</a>
-  </p>
-</p>
-<br>
-<p align="center">
- <a href="https://amzn.to/3ZmTyb2" target="_blank">React Key Concepts: Consolidate your knowledge of React’s core features (2nd ed. Edition)</a>
-</p>
+| Requirement | Version |
+|-------------|---------|
+| React Native | >= 0.70.0 |
+| iOS | >= 13.4 |
+| Android | API 21+ (Android 5.0) |
+| Expo | SDK 50+ |
+| TypeScript | >= 5.0 (optional) |
 
-# Getting started
+---
 
-## Installation
+## 📦 Installation
 
-### Install dependencies
+### Expo Projects
 
-Yarn:
 ```bash
-yarn add react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
+npx expo install react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
 ```
 
-Npm:
+### Bare React Native Projects
+
+**Step 1:** Install the packages
 
+Using yarn:
 ```bash
-npm install --save react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
+yarn add react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
 ```
 
-Expo
+Using npm:
 ```bash
-npx expo install react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
+npm install --save react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller
 ```
 
-### Non-expo users
+**Step 2:** Install iOS pods
 
 ```bash
 npx pod-install
 ```
 
-### Setup react-native-reanimated
+**Step 3:** Configure react-native-reanimated
 
-Follow guide: [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#step-2-add-reanimateds-babel-plugin)
+Follow the [react-native-reanimated installation guide](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/getting-started/#step-2-add-reanimateds-babel-plugin) to add the Babel plugin.
+
+---
 
-## Examples
+## 🚀 Usage
 
-### Basic usage
+### Basic Example
 
 ```jsx
 import React, { useState, useCallback, useEffect } from 'react'
-import { Platform } from 'react-native'
 import { GiftedChat } from 'react-native-gifted-chat'
-import { useSafeAreaInsets } from 'react-native-safe-area-context'
+import { useHeaderHeight } from '@react-navigation/elements'
 
 export function Example() {
   const [messages, setMessages] = useState([])
-  const insets = useSafeAreaInsets()
 
-  // If you have a tab bar, include its height
-  const tabbarHeight = 50
-  const keyboardTopToolbarHeight = Platform.select({ ios: 44, default: 0 })
-  const keyboardVerticalOffset = insets.bottom + tabbarHeight + keyboardTopToolbarHeight
+  // keyboardVerticalOffset = distance from screen top to GiftedChat container
+  // useHeaderHeight() returns status bar + navigation header height
+  const headerHeight = useHeaderHeight()
 
   useEffect(() => {
     setMessages([
@@ -186,22 +158,51 @@ export function Example() {
       user={{
         _id: 1,
       }}
-
-      keyboardAvoidingViewProps={{ keyboardVerticalOffset }}
+      keyboardAvoidingViewProps={{ keyboardVerticalOffset: headerHeight }}
     />
   )
 }
 ```
 
-### Other examples
+> **💡 Tip:** Check out more examples in the [`example`](example) directory including Slack-style messages, quick replies, and custom components.
+
+---
+
+## 📊 Data Structure
+
+Messages, system messages, and quick replies follow the structure defined in [Models.ts](src/Models.ts).
+
+<details>
+<summary><strong>Message Object Structure</strong></summary>
 
-Check out code of [`examples`](example)
+```typescript
+interface 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)
+}
+```
 
-## Data structure
+</details>
 
-Messages, system messages, quick replies etc.: [data structure](src/Models.ts)
+---
 
-## Props
+## 📖 Props Reference
 
 ### Core Configuration
 
@@ -219,16 +220,51 @@ Messages, system messages, quick replies etc.: [data structure](src/Models.ts)
 
 ### Keyboard & Layout
 
-- **`keyboardProviderProps`** _(Object)_ - Props to be passed to the [`KeyboardProvider`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-provider) for keyboard handling.
-- **`keyboardAvoidingViewProps`** _(Object)_ - Props to be passed to the [`KeyboardAvoidingView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-avoiding-view). The `behavior` prop defaults to `'padding'`.
+- **`keyboardProviderProps`** _(Object)_ - Props to be passed to the [`KeyboardProvider`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/keyboard-provider) 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)
+- **`keyboardAvoidingViewProps`** _(Object)_ - Props to be passed to the [`KeyboardAvoidingView`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-avoiding-view). 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 `true`
 
+#### Understanding `keyboardVerticalOffset`
+
+The [`keyboardVerticalOffset`](https://kirillzyusko.github.io/react-native-keyboard-controller/docs/api/components/keyboard-avoiding-view#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:
+- Status bar height
+- Navigation header height (on iOS, `useHeaderHeight()` already includes status bar)
+
+**How to use:**
+
+```jsx
+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 returns `0`, 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.
+
 ### Text Input & Composer
 
 - **`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 field
 - **`isSendButtonAlwaysVisible`** _(Bool)_ - Always show send button in input text composer; default `false`, show only when text input is not empty
+- **`isTextOptional`** _(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 `44`
@@ -253,7 +289,7 @@ Messages, system messages, quick replies etc.: [data structure](src/Models.ts)
 - **`renderLoading`** _(Component | Function)_ - Render a loading view when initializing
 - **`renderChatEmpty`** _(Component | Function)_ - Custom component to render in the ListView when messages are empty
 - **`renderChatFooter`** _(Component | Function)_ - Custom component to render below the MessagesContainer (separate from the ListView)
-- **`listProps`** _(Object)_ - Extra props to be passed to the messages [`<FlatList>`](https://reactnative.dev/docs/flatlist)
+- **`listProps`** _(Object)_ - Extra props to be passed to the messages [`<FlatList>`](https://reactnative.dev/docs/flatlist). Supports all FlatList props including `maintainVisibleContentPosition` for keeping scroll position when new messages arrive (useful for AI chatbots).
 
 ### Message Bubbles & Content
 
@@ -352,6 +388,10 @@ See full example in [LinksExample](example/components/chat-examples/LinksExample
 - **`dateFormat`** _(String)_ - Format to use for rendering dates; default is `'D MMMM'` (see [Day.js Format](https://day.js.org/docs/en/display/format))
 - **`dateFormatCalendar`** _(Object)_ - Format to use for rendering relative times; default is `{ sameDay: '[Today]' }` (see [Day.js Calendar](https://day.js.org/docs/en/plugin/calendar))
 - **`renderDay`** _(Component | Function)_ - Custom day above a message
+- **`dayProps`** _(Object)_ - Props to pass to the Day component:
+  - `containerStyle` - Custom style for the day container
+  - `wrapperStyle` - Custom style for the day wrapper
+  - `textProps` - Props to pass to the Text component (e.g., `style`, `allowFontScaling`, `numberOfLines`)
 - **`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`
@@ -394,46 +434,214 @@ See [Quick Replies example in messages.ts](example/example-expo/data/messages.ts
 - **`quickReplyContainerStyle`** _(StyleProp<ViewStyle>)_ - Custom container style for quick replies
 - **`renderQuickReplySend`** _(Function)_ - Custom quick reply **send** view
 
+### Reply to Messages
+
+Gifted 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 `ReanimatedSwipeable` from `react-native-gesture-handler` and `react-native-reanimated` for smooth, performant animations.
+
+#### Basic Usage
+
+```tsx
+<GiftedChat
+  messages={messages}
+  onSend={onSend}
+  user={{ _id: 1 }}
+  reply={{
+    swipe: {
+      isEnabled: true,
+      direction: 'left', // swipe left to reply
+    },
+  }}
+/>
+```
+
+#### Reply Props (Grouped)
+
+The `reply` prop accepts an object with the following structure:
+
+```typescript
+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
+}
+```
+
+#### ReplyMessage Structure
+
+When a message has a reply, it includes a `replyMessage` property:
+
+```typescript
+interface ReplyMessage {
+  _id: string | number
+  text: string
+  user: User
+  image?: string
+  audio?: string
+}
+```
+
+#### Advanced Example with External State
+
+```tsx
+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),
+  }}
+/>
+```
+
+#### Smooth Animations
+
+The reply preview automatically animates when:
+- **Appearing**: Smoothly expands from zero height with fade-in effect
+- **Disappearing**: Smoothly collapses with fade-out effect
+- **Content changes**: Smoothly transitions when replying to a different message
+
+These animations use `react-native-reanimated` for 60fps performance.
+
 ### Scroll to Bottom
 
 - **`isScrollToBottomEnabled`** _(Bool)_ - Enables the scroll to bottom Component (Default is false)
 - **`scrollToBottomComponent`** _(Function)_ - Custom Scroll To Bottom Component container
 - **`scrollToBottomOffset`** _(Integer)_ - Custom Height Offset upon which to begin showing Scroll To Bottom Component (Default is 200)
-- **`scrollToBottomStyle`** _(Object)_ - Custom style for Bottom Component container
+- **`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.)
 
-## Notes for Android
+### Maintaining Scroll Position (AI Chatbots)
 
-If you are using Create React Native App / Expo, no Android specific installation steps are required -- you can skip this section. Otherwise, we recommend modifying your project configuration as follows.
+For AI chat interfaces where long responses arrive and you don't want to disrupt the user's reading position, use [`maintainVisibleContentPosition`](https://reactnative.dev/docs/scrollview#maintainvisiblecontentposition) via `listProps`:
 
-- Make sure you have `android:windowSoftInputMode="adjustResize"` in your `AndroidManifest.xml`:
+```tsx
+// Basic usage - always maintain scroll position
+<GiftedChat
+  listProps={{
+    maintainVisibleContentPosition: {
+      minIndexForVisible: 0,
+    },
+  }}
+/>
 
-  ```xml
-  <activity
-    android:name=".MainActivity"
-    android:label="@string/app_name"
-    android:windowSoftInputMode="adjustResize"
-    android:configChanges="keyboard|keyboardHidden|orientation|screenSize">
-  ```
+// With auto-scroll threshold - auto-scroll if within 10 pixels of newest content
+<GiftedChat
+  listProps={{
+    maintainVisibleContentPosition: {
+      minIndexForVisible: 0,
+      autoscrollToTopThreshold: 10,
+    },
+  }}
+/>
 
-- For **Expo**, there are at least 2 solutions to fix it:
+// Conditionally enable based on scroll state (recommended for chatbots)
+const [isScrolledUp, setIsScrolledUp] = useState(false)
 
-  - Append [`KeyboardAvoidingView`](https://reactnative.dev/docs/keyboardavoidingview) after GiftedChat. This should only be done for Android, as `KeyboardAvoidingView` may conflict with the iOS keyboard avoidance already built into GiftedChat, e.g.:
+<GiftedChat
+  listProps={{
+    onScroll: (event) => {
+      setIsScrolledUp(event.contentOffset.y > 50)
+    },
+    maintainVisibleContentPosition: isScrolledUp
+      ? { minIndexForVisible: 0, autoscrollToTopThreshold: 10 }
+      : undefined,
+  }}
+/>
+```
 
+---
+
+## 📱 Platform Notes
+
+### Android
+
+<details>
+<summary><strong>Keyboard configuration</strong></summary>
+
+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`:
+
+```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 GiftedChat (Android only):
+
+```jsx
 <View style={{ flex: 1 }}>
    <GiftedChat />
-   {
-      Platform.OS === 'android' && <KeyboardAvoidingView behavior="padding" />
-   }
+   {Platform.OS === 'android' && <KeyboardAvoidingView behavior="padding" />}
 </View>
 ```
 
-## Notes for local development
+</details>
+
+### Web (react-native-web)
 
-#### With create-react-app
+<details>
+<summary><strong>With create-react-app</strong></summary>
 
-1. `yarn add -D react-app-rewired`
-2. `touch config-overrides.js`
+1. Install react-app-rewired: `yarn add -D react-app-rewired`
+2. Create `config-overrides.js`:
 
 ```js
 module.exports = function override(config, env) {
@@ -453,23 +661,30 @@ module.exports = function override(config, env) {
       },
     },
   })
-
   return config
 }
 ```
 
-> You will find an example and a **web demo** here: [xcarpentier/gifted-chat-web-demo](https://github.com/xcarpentier/gifted-chat-web-demo)
+> **Examples:**
+> - [xcarpentier/gifted-chat-web-demo](https://github.com/xcarpentier/gifted-chat-web-demo)
+> - [Gatsby example](https://github.com/xcarpentier/clean-archi-boilerplate/tree/develop/apps/web)
+
+</details>
+
+---
+
+## 🧪 Testing
 
-> Another example with **Gatsby** : [xcarpentier/clean-archi-boilerplate](https://github.com/xcarpentier/clean-archi-boilerplate/tree/develop/apps/web)
+<details>
+<summary><strong>Triggering layout events in tests</strong></summary>
 
-## Testing
-`TEST_ID` is exported as constants that can be used in your testing library of choice
+`TEST_ID` is exported as constants that can be used in your testing library of choice.
 
-Gifted Chat uses `onLayout` to determine the height of the chat container. To trigger `onLayout` during your tests, you can run the following bits of code.
+Gifted Chat uses `onLayout` to determine the height of the chat container. To trigger `onLayout` during your tests:
 
 ```typescript
-const WIDTH = 200; // or any number
-const HEIGHT = 2000; // or any number
+const WIDTH = 200
+const HEIGHT = 2000
 
 const loadingWrapper = getByTestId(TEST_ID.LOADING_WRAPPER)
 fireEvent(loadingWrapper, 'layout', {
@@ -482,37 +697,144 @@ fireEvent(loadingWrapper, 'layout', {
 })
 ```
 
-## Questions
+</details>
+
+---
+
+## 📦 Example App
+
+The repository includes a comprehensive example app demonstrating all features:
+
+```bash
+# Clone and install
+git clone https://github.com/FaridSafi/react-native-gifted-chat.git
+cd react-native-gifted-chat/example
+yarn install
+
+# Run on iOS
+npx expo run:ios
+
+# Run on Android
+npx expo run:android
+
+# Run on Web
+npx expo start --web
+```
+
+The example app showcases:
+- 💬 Basic chat functionality
+- 🎨 Custom message bubbles and avatars
+- ↩️ Reply to messages with swipe gesture
+- ⚡ Quick replies (bot-style)
+- ✍️ Typing indicators
+- 📎 Attachment actions
+- 🔗 Link parsing and custom matchers
+- 🌐 Web compatibility
+
+---
+
+## ❓ Troubleshooting
+
+<details>
+<summary><strong>TextInput is hidden on Android</strong></summary>
+
+Make sure you have `android:windowSoftInputMode="adjustResize"` in your `AndroidManifest.xml`. See [Android configuration](#android) above.
+
+</details>
+
+<details>
+<summary><strong>How to set Bubble color for each user?</strong></summary>
 
-- [How can I set Bubble color for each user?](https://github.com/FaridSafi/react-native-gifted-chat/issues/672)
-- [How can I pass style props to InputToolbar design and customize its color and other styles properties?](https://github.com/FaridSafi/react-native-gifted-chat/issues/662)
-- [How can I change the color of the message box?](https://github.com/FaridSafi/react-native-gifted-chat/issues/640)
-- [Is there a way to manually dismiss the keyboard?](https://github.com/FaridSafi/react-native-gifted-chat/issues/647)
-- [I want to implement a popover that pops right after clicking on a specific avatar,
-  what is the best implementation in this case and how?](https://github.com/FaridSafi/react-native-gifted-chat/issues/660)
-- [Why TextInput is hidden on Android?](https://github.com/FaridSafi/react-native-gifted-chat/issues/680#issuecomment-359699364)
-- [How to use renderLoading?](https://github.com/FaridSafi/react-native-gifted-chat/issues/298)
-- [Can I use MySql to save the message?](https://github.com/FaridSafi/react-native-gifted-chat/issues/738)
+See [this issue](https://github.com/FaridSafi/react-native-gifted-chat/issues/672) for examples.
 
-## You have a question?
+</details>
 
-1. Please check this readme and you might find a response
-1. Please ask on StackOverflow first: https://stackoverflow.com/questions/tagged/react-native-gifted-chat
-1. Find responses in existing issues
-1. Try to keep issues for issues
+<details>
+<summary><strong>How to customize InputToolbar styles?</strong></summary>
 
-## Hire an expert
+See [this issue](https://github.com/FaridSafi/react-native-gifted-chat/issues/662) for examples.
 
-Looking for a React Native freelance expert with more than 14 years of experience? Contact Xavier from his [website](https://xaviercarpentier.com)
+</details>
 
-## Author
+<details>
+<summary><strong>How to manually dismiss the keyboard?</strong></summary>
+
+See [this issue](https://github.com/FaridSafi/react-native-gifted-chat/issues/647) for examples.
+
+</details>
+
+<details>
+<summary><strong>How to use renderLoading?</strong></summary>
+
+See [this issue](https://github.com/FaridSafi/react-native-gifted-chat/issues/298) for examples.
+
+</details>
+
+---
+
+## 🤔 Have a Question?
+
+1. Check this README first
+2. Search [existing issues](https://github.com/FaridSafi/react-native-gifted-chat/issues)
+3. Ask on [StackOverflow](https://stackoverflow.com/questions/tagged/react-native-gifted-chat)
+4. Open a new issue if needed
+
+---
 
-Feel free to ask me questions on Twitter [@FaridSafi](https://www.x.com/FaridSafi) or [@xcapetir](https://www.x.com/xcapetir)
+## 🤝 Contributing
 
-## Maintainer
+Contributions are welcome! Please feel free to submit a Pull Request.
 
-Have any questions? Reach out to [Kesha Antonov](https://github.com/kesha-antonov)
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Install dependencies (`yarn install`)
+4. Make your changes
+5. Run tests (`yarn test`)
+6. Run linting (`yarn lint`)
+7. Build the library (`yarn build`)
+8. Commit your changes (`git commit -m 'Add amazing feature'`)
+9. Push to the branch (`git push origin feature/amazing-feature`)
+10. Open a Pull Request
 
-Please note that I'm maintaining this project in my free time for free. If you find any issues, feel free to open them, and I'll do my best to address them as time permits.
+### Development Setup
 
-If you consider my work helpful please consider [become a backer](https://github.com/sponsors/kesha-antonov), I'll have more time to work on open source. Thanks!
+```bash
+# Install dependencies
+yarn install
+
+# Build the library
+yarn build
+
+# Run tests
+yarn test
+
+# Run linting
+yarn lint
+
+# Full validation
+yarn prepublishOnly
+```
+
+---
+
+## 👥 Authors
+
+**Original Author:** [Farid Safi](https://www.x.com/FaridSafi)
+
+**Co-maintainer:** [Xavier Carpentier](https://www.x.com/xcapetir) - [Hire Xavier](https://xaviercarpentier.com)
+
+**Maintainer:** [Kesha Antonov](https://github.com/kesha-antonov)
+
+> Please note that this project is maintained in free time. If you find it helpful, please consider [becoming a sponsor](https://github.com/sponsors/kesha-antonov).
+
+---
+
+## 📄 License
+
+[MIT](LICENSE)
+
+---
+
+<p align="center">
+  <sub>Built with ❤️ by the React Native community</sub>
+</p>