Guide · Open source

How to use react-native-gifted-chat: install and build a chat screen

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-native-gifted-chat is a TypeScript component library that gives a React Native app a complete chat screen, including a message list, input box, avatars and timestamps. This guide shows how to install it in an Expo or bare React Native project, render a basic chat screen and wire up sending messages. It is written for developers who are comfortable with React components but have not built a chat UI before.

Gifted ChatFaridSafi/react-native-gifted-chat · ★ 14.4k · MIT Install options & downloads

Quick start

1Confirm your environment. Check that your project meets the React Native, Expo, iOS and Android minimum versions listed in the README.
2Install the packages. Run npx expo install for Expo projects, or yarn add or npm install for bare React Native, using the full package list.
3Finish native setup. On bare React Native, run npx pod-install and add the react-native-reanimated Babel plugin as its guide describes.
4Import GiftedChat. Import GiftedChat from react-native-gifted-chat into the screen where you want chat.
5Pass messages and user. Give GiftedChat a messages array and a user object with an _id.
6Handle onSend. Use GiftedChat.append inside onSend to add new messages to your state.

Check the requirements before you install

The library expects React Native 0.70.0 or newer, or Expo SDK 50 or newer. On iOS it needs version 13.4 or higher, and on Android API 21 (Android 5.0) or higher. TypeScript 5.0 or newer is optional.

React Native >= 0.70.0 or Expo SDK 50+
iOS >= 13.4 or Android API 21+
TypeScript >= 5.0 (optional)

Install react-native-gifted-chat and its dependencies

Install the library together with its companion packages. For Expo projects, use npx expo install. For bare React Native projects, use yarn or npm. The README lists react-native-reanimated, react-native-gesture-handler, react-native-safe-area-context and react-native-keyboard-controller as required alongside the library itself.

On bare React Native projects, run the iOS pod install after adding the packages. Also follow the react-native-reanimated installation guide to add its Babel plugin.

Expo: use npx expo install with the full package list
Bare React Native: use yarn add or npm install --save with the full package list
Bare React Native on iOS: run npx pod-install
Configure the react-native-reanimated Babel plugin as described in its guide

npx expo install react-native-gifted-chat react-native-reanimated react-native-gesture-handler react-native-safe-area-context react-native-keyboard-controller

Render a basic chat screen with GiftedChat

Import GiftedChat from the package and pass it a messages array, an onSend handler and a user object. The user object identifies the current person by _id. Each message needs an _id, text, createdAt, and a user object.

Use GiftedChat.append to add newly sent messages to the existing list. The example also passes keyboardAvoidingViewProps with a keyboardVerticalOffset set from useHeaderHeight, so the keyboard does not cover the input when a navigation header is present. The offset is the distance from the top of the screen to the GiftedChat container.

messages: the array of IMessage objects to display
onSend: called when the user sends a message
user: the current user, identified by _id
keyboardAvoidingViewProps: lets you set keyboardVerticalOffset

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([])
  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 }}
    />
  )
}

Understand the message data structure

Messages follow the IMessage interface defined in the library's Models.ts file. The required fields shown in the source are _id (string or number), text, createdAt (Date or number) and user. Optional fields include image and video.

Quick replies and system messages also follow structures defined in the same models file.

_id: string or number
text: the message body
createdAt: a Date or a number
user: the sender object
image and video: optional

Add features such as replies and quick replies

The README lists features such as swipe-to-reply, load earlier messages, copy to clipboard, smart link parsing, typing indicator, message status ticks, scroll-to-bottom, quick replies and emoji reactions. Each feature has its own section in the README's Usage and Props Reference, which you should read before enabling it.

You can also override chat components with your own implementations, which the README describes as a core feature of the library.

Swipe-to-reply with reply preview
Load earlier messages with pagination
Quick reply buttons
Emoji reactions on long-press
Typing indicator and message status ticks
Custom component overrides

What people use it for

A chat or messaging screen inside a React Native app
A drop-in chat interface in an Expo project
A support or customer messaging screen that needs quick replies
A chat screen with swipe-to-reply and emoji reactions
A custom-styled chat UI where you replace individual components

Frequently asked questions

Is react-native-gifted-chat free to use?

The package is released under the MIT licence, as stated in the repository. Check the LICENSE file in the repository for the full terms before using it in a commercial product.

Does react-native-gifted-chat work with Expo?

Yes. The README includes a dedicated Expo installation section that uses npx expo install with the required companion packages. It also lists Expo SDK 50 or newer as a requirement.

What do I need to install with react-native-gifted-chat?

The README lists react-native-reanimated, react-native-gesture-handler, react-native-safe-area-context and react-native-keyboard-controller as packages to install alongside it. Bare React Native projects also need npx pod-install and the reanimated Babel plugin.

Is react-native-gifted-chat still maintained?

The README says the package is now in maintenance mode and no longer receives new features. It recommends the maintained fork @kesha-antonov/react-native-chat for new projects, and says migrating is mostly a rename.

What are the alternatives to react-native-gifted-chat?

The analysis lists @kesha-antonov/react-native-chat, react-native-chat-ui-kit and stream-chat-react-native as comparable projects. For new work, the README points to the maintained fork first.

Why is my keyboard covering the chat input?

The README's example sets keyboardAvoidingViewProps with keyboardVerticalOffset, using useHeaderHeight from @react-navigation/elements. This offset is the distance from the top of the screen to the GiftedChat container, so set it to match your header.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use react-native-gifted-chat if you are maintaining an existing app that already uses it and need a complete, customizable chat screen in React Native or Expo. If you are starting a new project, the README recommends the maintained fork @kesha-antonov/react-native-chat instead. It is a developer component, not a finished chat app, so non-coders should look elsewhere.

Install options & downloads