This tutorial teaches you how to build a fully featured mobile messaging app with Expo and Stream's Chat Expo SDK - channel list, message composer, reactions, threads, typing indicators, and file uploads, running on both iOS and Android. You can use it as the foundation for any type of in-app chat.
This page works for both humans and AI coding agents: every step is a file operation or a shell command, every step has a verification checkpoint, and the few steps that need a human are explicitly marked.
This chat tutorial uses Stream's edge network for optimal performance. Stream powers chat, activity feeds and video for thousands of apps and over a billion end users.
This tutorial uses Stream Chat Expo SDK v10. It has been tested with the following versions:
- Expo SDK
58.0.23, with React Native0.88.1and React19.3.0. The SDK needs Expo SDK 53 or later, with the New Architecture enabled - Stream Chat Expo SDK 10.0.0 with
stream-chat10.0.0 react-native-reanimated4.7.1,react-native-worklets0.13.0,react-native-gesture-handler3.3.0,react-native-safe-area-context5.11.1,react-native-svg15.16.0,react-native-teleport1.2.3,@react-native-community/netinfo12.0.1 andexpo-image-manipulator58.0.16- Expo Router
58.0.30andreact-native-screens4.30.1 - Node 22.18 or later, which
stream-chat10 needs to install, and npm, whichcreate-expo-appsets up
The SDK supports the React Native New Architecture only. If your app still uses the old architecture, migrate that first before integrating the SDK. See Installation.
We also have a sample project available if you want to compare your setup against a working app.
Using the React Native CLI instead of Expo? Follow the React Native CLI chat tutorial.
Choose your path
This tutorial has two paths. In Path A you let your AI agent build the app. In Path B you build it yourself, step by step, on Expo. Both paths end with the same working chat app, so pick one instead of working through both.
Path A - Let your AI agent build it (recommended)
Install the Stream CLI once, then add the skills. This gives Claude Code, Cursor, or Codex the Expo integration patterns and current SDK APIs, so it builds against real docs instead of stale training data.
# Install the getstream CLI
curl -fsSL https://getstream.io/cli.sh | bash
# Install the skills (router, docs, and builder). The React Native pack installs
# on demand the first time it's needed, or add it explicitly:
getstream skills
getstream skills stream-react-nativeThen ask your agent:
/stream-react-native Build an Expo chat app with Expo Router, a channel list screen,
a channel screen, and a thread screen. Use Stream Chat Expo SDK v10
(stream-chat-expo 10.0.0 or later). Provision credentials with the CLI
(create/select my org and app, mint a token), or fall back to the tutorial demo
credentials if I'm not logged in.Where you come in. The agent handles credentials and code itself. It stops for you twice: when getstream init opens your browser to sign in and pick an app (new accounts get an organization created in that flow), and when the app first runs on a simulator or emulator - launching one and trusting a native build is a human call.
Want to get the sign-in out of the way first? Run getstream init before you prompt the agent - it picks up the initialized project from there.
Checkpoint: build a development build if the agent hasn't (npx expo run ios or npx expo run android). You should see a channel list, be able to open a channel, and send a message.
Skim Important Building Blocks if you want to understand what the agent wrote before you extend it.
Path B - Build it manually
Choose this path if you'd rather write the code yourself, or you want to understand what the SDK is doing before you hand it to an agent. Titled code blocks show the parts of that file that changed at that point in the tutorial; comments such as // ...rest of the code mark everything you keep as is.
For AI assistants reading this page: append
.mdto any Stream docs URL for a clean Markdown version. A condensed index for the React Native Chat SDK is athttps://getstream.io/chat/docs/sdk/react-native/llms.txt. Prefer these over parsing HTML.
Important Building Blocks
Five pieces, one mental model:
-
useCreateChatClient- creates theStreamChatclient and manages its connection. The client abstracts API calls into methods, holds the state of channels, threads and message lists, and handles real-time events. Use this hook once per application; anywhere further down the tree, reach foruseChatContextinstead. -
OverlayProvider- the outermost Stream component, mounted near the root of your app. It hosts the full-screen image viewer and the message context menu. -
ChatandChannel- React context providers.Chatholds the client and connection state;Channelgives one channel to the message list and the composer inside it.Theme and translations come from both
OverlayProviderandChat- each one providesThemeContextandTranslationContext, so components read whichever is closest above them. -
UI components -
ChannelList,MessageList,MessageComposer, andThread.ChannelListrenders aChannelPaginatorthat your app creates, andThreadrenders next toChannelon a screen of its own. Use them as-is, or replace them as you see fit. -
WithComponents- the customization surface. Swap any SDK-owned view for your own; everything you don't name keeps its default. It nests, so inner overrides merge over outer ones and the closest provider wins.
The SDK does not drill props - components read what they need from context, via hooks such as useChannel, useMessageContext, and useTheme. The providers and context hooks page lists every context, the hook that reads it, and the component that provides it.
You'll get a working app with the default UI first, then theme it, then replace individual components. Deeper customizations are linked at the end.
Prerequisites
You need a working Expo development environment. Follow Expo's Set Up Your Environment guide, choosing a development build as the target - stream-chat-expo ships native code, so it needs a development build rather than Expo Go. Use Node 22.18 or later, because stream-chat 10 needs it to install.
Step 0 - Set up the project
To get started, create a new application with the Expo CLI:
# Initialize the app
npx create-expo-app MyStreamChatApp --template blank-typescript
# Navigate to the app directory
cd MyStreamChatAppInstall the Stream Chat Expo SDK together with stream-chat:
npx expo install stream-chat-expo stream-chat -- --legacy-peer-depsThe SDK depends on stream-chat, the JavaScript client that holds the state. Your app imports from it too, for example ChannelPaginator and the types, so add it next to the SDK and upgrade both together. Exactly one copy of stream-chat must resolve.
--legacy-peer-deps keeps npm from adding a second copy of React next to the SDK. The SDK's Markdown dependency declares React 18 as a peer, and without the flag npm installs React 18 under node_modules/stream-chat-expo, which makes the app fail on its first render with Cannot read property 'useState' of null. The command also adds the stream-chat-expo config plugin to app.json.
Stream Chat requires a set of peer dependencies for the core React Native UI experience. Follow the installation steps for each dependency to ensure everything is configured correctly.
Install the required peer dependencies:
npx expo install @react-native-community/netinfo expo-image-manipulator react-native-gesture-handler react-native-reanimated react-native-safe-area-context react-native-svg react-native-teleport react-native-workletsApplication level setup
The most important steps to get started are:
-
Import
react-native-gesture-handlerat the top of your app entry. With Expo Router, we will do that inapp/_layout.tsxin Step 2. -
Wrap your app root with both
SafeAreaProviderandGestureHandlerRootView. We will also do that inapp/_layout.tsx. -
Add a
schemetoapp.json. Expo Router needs it for deep linking, and it has to be set before the first native build:
{
"expo": {
"name": "MyStreamChatApp",
"scheme": "mystreamchatapp"
}
}If you enable optional features such as audio recording, camera access, or media library access, make sure you also add the required platform permissions for those features.
Now build and run the app. This compiles a development build, installs it, and starts the bundler for you:
npx expo run iosnpx expo run androidOnce the development build is installed, you can start the bundler on its own with npx expo start --dev-client instead of rebuilding, and only re-run npx expo run after you add or change a native dependency.
Checkpoint: stream-chat-expo, stream-chat and the peer dependencies appear in package.json, and the development build launches and shows the Expo template screen on a simulator or emulator.


Step 1 - Define the type system
Declare the SDK interfaces in your app so Stream's extended types resolve correctly. The module declaration needs to take place so that types are properly resolved within your application. You can read more about this in Data conventions.
To do this, you can create a new TypeScript declaration file and add the following code to it:
import "stream-chat";
import type {
DefaultAttachmentData,
DefaultChannelData,
DefaultEventData,
DefaultMemberData,
DefaultMessageData,
DefaultPollData,
DefaultPollOptionData,
DefaultReactionData,
DefaultThreadData,
DefaultUserData,
} from "stream-chat-expo";
declare module "stream-chat" {
/* eslint-disable @typescript-eslint/no-empty-object-type */
interface CustomAttachmentData extends DefaultAttachmentData {}
interface CustomChannelData extends DefaultChannelData {}
interface CustomEventData extends DefaultEventData {}
interface CustomMemberData extends DefaultMemberData {}
interface CustomUserData extends DefaultUserData {}
interface CustomMessageData extends DefaultMessageData {}
interface CustomPollOptionData extends DefaultPollOptionData {}
interface CustomPollData extends DefaultPollData {}
interface CustomReactionData extends DefaultReactionData {}
interface CustomThreadData extends DefaultThreadData {}
/* eslint-enable @typescript-eslint/no-empty-object-type */
}This will make sure that all of the SDK interfaces are properly resolved and the types are correct. Additionally, this will allow you to declare your own custom data if your integration requires it. Your custom fields are typed under custom, for example message.custom and channel.data.custom.
Checkpoint: custom-types.d.ts exists at the project root.
Step 2 - Add navigation
The Stream Chat SDK does not handle navigation, but Expo Router makes it easy to set up the channel list, channel, and thread screens we need for the application.
Install the following packages to get started with Expo Router, as mentioned in their documentation.
npx expo install expo-router react-native-screens expo-linking expo-constants expo-status-barThe command also adds the expo-router config plugin to app.json. After this step, follow the Expo Router installation guide to make sure the entry point is set up correctly for your app. Reminder that you already added the scheme in Step 0. No Babel setup is needed.
In particular, make sure your package.json includes the Expo Router entry point:
{
"main": "expo-router/entry"
}react-native-screens ships native code, so rebuild the development build with npx expo run ios or npx expo run android rather than only restarting the bundler.
We'll set up a simple stack to hold the necessary screens for navigation in our app, and start with a basic HomeScreen, which we will replace later with chat related screens.
You can copy-paste the following code into the app/_layout.tsx file:
import "react-native-gesture-handler";
import { Stack } from "expo-router";
import { StatusBar } from "expo-status-bar";
import { StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
export default function RootLayout() {
return (
<SafeAreaProvider>
<GestureHandlerRootView style={styles.container}>
<StatusBar style="auto" />
<Stack screenOptions={{ headerTransparent: false }} />
</GestureHandlerRootView>
</SafeAreaProvider>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
},
});The StatusBar keeps the status bar icons dark, so they stay visible on the light header on Android. On iOS 26, the header of the native stack is see-through by default and a list scrolls under it, so headerTransparent: false keeps it opaque and every screen starts below it.
Then create a basic HomeScreen in app/index.tsx:
import { Stack } from "expo-router";
import { StyleSheet, Text, View } from "react-native";
export default function HomeScreen() {
return (
<>
<Stack.Screen options={{ title: "Home" }} />
<View style={styles.centered}>
<Text>Home Screen</Text>
</View>
</>
);
}
const styles = StyleSheet.create({
centered: {
alignItems: "center",
flex: 1,
justifyContent: "center",
},
});Checkpoint: the app shows a "Home" header and the text Home Screen centered on the page.


Step 3 - Credentials
The next step needs four values: an API key that identifies your Stream application to our servers, a user ID and user token that authorize the current chat user, and a user name used as their display name.
There are two ways to get them. Pick one, then finish with the "Store the credentials" step.
Option 1 - Your own Stream app, via the Stream CLI
The getstream CLI provisions all of it in one flow. Run these from the MyStreamChatApp directory you created in Step 0.
1. Install the CLI (skip if you did this in Path A):
curl -fsSL https://getstream.io/cli.sh | bash2. Initialize the project. This one command authenticates you, lets you create or select an organization and app, and writes the project credentials. New to Stream? The sign-in flow creates your organization. Already have an org or an app? It lets you pick them.
getstream initHuman checkpoint: getstream init opens a browser to authenticate. Agents: run it, then ask the human to finish signing in before continuing. It's required first - env, token, and api commands fail with "stream project is not initialized" until it runs.
3. Write your API key into the project. Expo is a first-class target for the CLI:
getstream env --target expoThis writes EXPO_PUBLIC_STREAM_API_KEY into .env and adds that file to .gitignore. The API secret is never written to a client target. Expo loads EXPO_PUBLIC_* variables into the bundle automatically, so you can read the key with process.env.EXPO_PUBLIC_STREAM_API_KEY instead of pasting it into your source.
4. Mint a user token for a user in your app (never expiring by default; add a TTL for production-like testing):
getstream token cleo
getstream token cleo --ttl 1d5. Seed a channel so your first launch isn't an empty list. Create the users first, then the channel:
getstream api UpdateUsers --request '{"users":{"cleo":{"id":"cleo","name":"Cleo"},"cara":{"id":"cara","name":"Cara"}}}'
getstream api GetOrCreateChannel --type messaging --id general \
--request '{"data":{"created_by_id":"cleo","custom":{"name":"General"},"members":[{"user_id":"cleo"},{"user_id":"cara"}]}}'You can also mint tokens with our token (JWT) generator utility. Learn more in the Tokens & Authentication documentation.
Option 2 - Pre-filled tutorial credentials, no account
Want to skip account setup entirely? Use these values in the "Store the credentials" step:
export const chatApiKey = "REPLACE_WITH_API_KEY";
export const chatUserId = "REPLACE_WITH_USER_ID";
export const chatUserName = "REPLACE_WITH_USER_NAME";
export const chatUserToken = "REPLACE_WITH_USER_TOKEN";Swap in your own credentials from Option 1 before building anything real. Tutorial credentials are shared and short lived.
Store the credentials
Whichever option you picked, put the four values in a small config file:
export const chatApiKey = "<your API key>";
export const chatUserId = "<your user id>";
export const chatUserName = "<your user name>";
export const chatUserToken = "<your user token>";On Option 1, read the API key from the .env file the CLI wrote instead of hardcoding it:
export const chatApiKey = process.env.EXPO_PUBLIC_STREAM_API_KEY!;For production apps, generate user tokens on your backend and return them to the client instead of hardcoding them in the app.
Checkpoint: chatConfig.ts holds four non-placeholder values, and the API key and token belong to the same Stream app.
Step 4 - Connect the user
Before rendering any chat UI, create a StreamChat client and connect the current user. The easiest way to do that in an Expo app is with the useCreateChatClient hook.
Create a small wrapper component that creates the client before rendering the app content:
import React, { PropsWithChildren } from "react";
import { Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { useCreateChatClient } from "stream-chat-expo";
import {
chatApiKey,
chatUserId,
chatUserName,
chatUserToken,
} from "../chatConfig";
const user = {
id: chatUserId,
name: chatUserName,
};
export const ChatWrapper = ({ children }: PropsWithChildren) => {
const chatClient = useCreateChatClient({
apiKey: chatApiKey,
userData: user,
tokenOrProvider: chatUserToken,
});
if (!chatClient) {
return (
<SafeAreaView>
<Text>Loading chat ...</Text>
</SafeAreaView>
);
}
return <>{children}</>;
};Note: Make sure you use the
useCreateChatClienthook only once per application. If you need the client instance somewhere down in the component tree, use theuseChatContexthook exported bystream-chat-expoto access it.
Checkpoint: components/ChatWrapper.tsx exists and the app still builds. Nothing changes on screen yet - ChatWrapper isn't mounted until Step 5, which is where you'll see the connection happen.
Step 5 - Add the providers
Three providers go around the stack: your own app context for the selected channel and thread, then Stream's OverlayProvider and Chat.
5.1 - Create the app context
Ideally, a context should store the current Channel and Thread selected by the user while moving through the app. Both are objects of the stream-chat client: the channel list gives you a Channel when the user picks a row, and the message list gives you a Thread when the user opens a message's replies.
Create contexts/AppContext.tsx:
import React, { PropsWithChildren, useState } from "react";
import type { Channel, Thread } from "stream-chat";
type AppContextValue = {
channel: Channel | undefined;
setChannel: (channel: Channel | undefined) => void;
thread: Thread | undefined;
setThread: (thread: Thread | undefined) => void;
};
export const AppContext = React.createContext<AppContextValue>({
channel: undefined,
setChannel: () => {},
thread: undefined,
setThread: () => {},
});
export const AppProvider = ({ children }: PropsWithChildren) => {
const [channel, setChannel] = useState<Channel>();
const [thread, setThread] = useState<Thread>();
return (
<AppContext.Provider value={{ channel, setChannel, thread, setThread }}>
{children}
</AppContext.Provider>
);
};
export const useAppContext = () => React.useContext(AppContext);To use the context, update app/_layout.tsx so it wraps the stack with both ChatWrapper and AppProvider:
import "react-native-gesture-handler";
import { Stack } from "expo-router";
import { StatusBar } from "expo-status-bar";
import { StyleSheet } from "react-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { SafeAreaProvider } from "react-native-safe-area-context";
import { ChatWrapper } from "../components/ChatWrapper";
import { AppProvider } from "../contexts/AppContext";
export default function RootLayout() {
return (
<SafeAreaProvider>
<GestureHandlerRootView style={styles.container}>
<ChatWrapper>
<AppProvider>
<StatusBar style="auto" />
<Stack screenOptions={{ headerTransparent: false }} />
</AppProvider>
</ChatWrapper>
</GestureHandlerRootView>
</SafeAreaProvider>
);
}
const styles = StyleSheet.create({
container: {
flex: 1,
},
});5.2 - Add the OverlayProvider
The OverlayProvider is the highest level of the Stream Chat components and must be used near the root of your application, below SafeAreaProvider.
The OverlayProvider allows users to open the full-screen image viewer and message context menu as overlays on top of the rest of the application. You can go through the available props here.
Update ChatWrapper so it wraps the app content in OverlayProvider:
import React, { PropsWithChildren } from "react";
import { Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { OverlayProvider, useCreateChatClient } from "stream-chat-expo";
import {
chatApiKey,
chatUserId,
chatUserName,
chatUserToken,
} from "../chatConfig";
const user = {
id: chatUserId,
name: chatUserName,
};
export const ChatWrapper = ({ children }: PropsWithChildren) => {
const chatClient = useCreateChatClient({
apiKey: chatApiKey,
userData: user,
tokenOrProvider: chatUserToken,
});
if (!chatClient) {
return (
<SafeAreaView>
<Text>Loading chat ...</Text>
</SafeAreaView>
);
}
return <OverlayProvider>{children}</OverlayProvider>;
};If you see some errors at this point, please refer to our troubleshooting guide.
5.3 - Add the Chat component
The Chat component provides the chat client, translations, and theme to the rest of the SDK.
Update ChatWrapper again so it wraps the app content with Chat inside OverlayProvider:
import React, { PropsWithChildren } from "react";
import { Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { Chat, OverlayProvider, useCreateChatClient } from "stream-chat-expo";
import {
chatApiKey,
chatUserId,
chatUserName,
chatUserToken,
} from "../chatConfig";
const user = {
id: chatUserId,
name: chatUserName,
};
export const ChatWrapper = ({ children }: PropsWithChildren) => {
const chatClient = useCreateChatClient({
apiKey: chatApiKey,
userData: user,
tokenOrProvider: chatUserToken,
});
if (!chatClient) {
return (
<SafeAreaView>
<Text>Loading chat ...</Text>
</SafeAreaView>
);
}
return (
<OverlayProvider>
<Chat client={chatClient}>{children}</Chat>
</OverlayProvider>
);
};Checkpoint: the app briefly shows Loading chat ... and then renders the Home Screen once the websocket connects. app/_layout.tsx wraps the stack in ChatWrapper and AppProvider, and ChatWrapper returns OverlayProvider -> Chat.
Step 6 - Add the channel list
The ChannelList component renders the channels of a ChannelPaginator in a FlatList.
6.1 - Add the channel list screen
Before configuring this component, let's set up a screen for the channel list by replacing HomeScreen in app/index.tsx with ChannelListScreen.
import { Stack } from "expo-router";
export default function ChannelListScreen() {
return (
<>
<Stack.Screen options={{ title: "Channels" }} />
</>
);
}6.2 - Display the channel list
A ChannelPaginator is the object behind a channel list. It holds the list's filters and sort order, queries the channels page by page, and keeps what it loaded. Your app creates it and registers it on client.channelManager, which keeps the list up to date as messages and other events arrive. ChannelList renders the paginator and loads its first page when it mounts.
The filters below show the messaging channels the current user is a member of, and sort puts the channel with the latest message first. Give every paginator an id of its own. Please check out Querying Channels for more information and various use cases of filters and sort, and Channel list paginators for how paginators work.
import { useEffect, useMemo } from "react";
import { Stack } from "expo-router";
import { ChannelPaginator } from "stream-chat";
import type { ChannelFilters, SortParamRequest } from "stream-chat";
import { ChannelList, useChatContext } from "stream-chat-expo";
import { chatUserId } from "../chatConfig";
const filters: ChannelFilters = {
members: { $in: [chatUserId] },
type: "messaging",
};
const sort: SortParamRequest[] = [{ direction: -1, field: "last_message_at" }];
export default function ChannelListScreen() {
const { client } = useChatContext();
const paginator = useMemo(
() => new ChannelPaginator({ client, filters, id: "my-channels", sort }),
[client],
);
useEffect(() => {
client.channelManager.insertPaginator({ paginator });
return () => {
client.channelManager.removePaginator(paginator);
paginator.dispose();
};
}, [client, paginator]);
return (
<>
<Stack.Screen options={{ title: "Channels" }} />
<ChannelList paginator={paginator} />
</>
);
}The useEffect registers the paginator when the screen mounts, and removes and disposes it when the screen unmounts. A paginator that is not registered shows its first page and then never changes. useChatContext gives the screen the client that Chat holds.
If you don't see any channels, the user is not a member of any yet. Seed one in Step 3, or drop the
membersfilter from thefiltersobject to list every messaging channel the user can read.
Checkpoint: the "Channels" screen lists the channels your user belongs to.


Step 7 - Channel screen
7.1 - Navigate to the channel screen
You can add the press handler for the list item within the ChannelList component using the onSelect prop. This is where you can add the logic for navigating to the channel screen, where we will render the message list and composer.
Let's implement the basic ChannelScreen component and logic for navigating from ChannelList to ChannelScreen.
Create a new route file at app/channel/[cid].tsx:
import { Stack } from "expo-router";
export default function ChannelScreen() {
return (
<>
<Stack.Screen options={{ title: "Channel" }} />
</>
);
}Then update ChannelListScreen so it stores the selected channel and navigates to the route:
import { Stack, useRouter } from "expo-router";
import { useAppContext } from "../contexts/AppContext";
// ...rest of the code
export default function ChannelListScreen() {
const router = useRouter();
const { client } = useChatContext();
const { setChannel } = useAppContext();
// ...existing paginator logic
return (
<>
<Stack.Screen options={{ title: "Channels" }} />
<ChannelList
onSelect={(channel) => {
setChannel(channel);
router.push({
pathname: "/channel/[cid]",
params: { cid: channel.cid },
});
}}
paginator={paginator}
/>
</>
);
}7.2 - Display the channel screen
The channel screen will comprise three main components:
MessageListcomponent used to render the list of messages sent in a channel.MessageComposercomponent used to render the input box needed to send messages, images, files, and commands to a channel.Channelcomponent that gives one channel to everything inside it. It also acts as a bridge between theMessageListandMessageComposercomponents.
The Channel component takes the channel as a prop. The MessageList and MessageComposer components don't need any props to be set, and we'll use the defaults set for these components.
Channel moves its content out of the keyboard's way, and the attachment picker needs to know how far up it may open. Pass the height of the navigation header, from useHeaderHeight(), as keyboardVerticalOffset and topInset. See Keyboard and insets.
import { Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { Stack } from "expo-router";
import { useHeaderHeight } from "expo-router/react-navigation";
import { Channel, MessageComposer, MessageList } from "stream-chat-expo";
import { useAppContext } from "../../contexts/AppContext";
export default function ChannelScreen() {
const { channel } = useAppContext();
const headerHeight = useHeaderHeight();
if (!channel) {
return (
<SafeAreaView>
<Text>Loading chat ...</Text>
</SafeAreaView>
);
}
return (
<>
<Stack.Screen options={{ title: "Channel" }} />
<Channel
channel={channel}
keyboardVerticalOffset={headerHeight}
topInset={headerHeight}
>
<MessageList />
<MessageComposer />
</Channel>
</>
);
}Checkpoint: tapping a channel opens it. You can send messages, long press a message to open the message menu and add a reaction, and use the built-in composer UI.


The default composer is text-only. Image and file attachments need the optional media packages - see the installation guide.
Step 8 - Thread screen
The Threads feature is similar to Slack's, which allows you to start a conversation about a particular message in a message list.
8.1 - Create the thread screen
Let's first set up a separate screen for the thread within our navigation stack.
Create a new route file at app/channel/[cid]/thread/[messageId].tsx:
import { Stack } from "expo-router";
export default function ThreadScreen() {
return (
<>
<Stack.Screen options={{ title: "Thread" }} />
</>
);
}8.2 - Navigate to the thread screen
As explained in the previous step, when a user long presses a message, it opens an overlay where the user can add a reaction and see many actions for the message.
MessageList accepts an onThreadSelect prop, which gets called with the Thread object when a user selects the "Thread Reply" action on the message overlay, or taps the replies of a message.
Update ChannelScreen so it stores the selected thread and navigates to ThreadScreen:
import { Stack, useRouter } from "expo-router";
// ...rest of the code
export default function ChannelScreen() {
const router = useRouter();
const { channel, setThread } = useAppContext();
const headerHeight = useHeaderHeight();
// ...existing loading state
return (
<>
<Stack.Screen options={{ title: "Channel" }} />
<Channel
channel={channel}
keyboardVerticalOffset={headerHeight}
topInset={headerHeight}
>
<MessageList
onThreadSelect={(thread) => {
setThread(thread);
router.push({
pathname: "/channel/[cid]/thread/[messageId]",
params: {
cid: channel.cid,
messageId: thread.id,
},
});
}}
/>
<MessageComposer />
</Channel>
</>
);
}8.3 - Display the thread screen
The Thread component renders next to Channel, on a screen of its own, and not inside it. It takes the Thread object you stored as the thread prop, and renders the children you give it: a MessageList that shows the replies, with the parent message above them, and a MessageComposer that sends replies.
Thread takes the same configuration props as Channel, such as keyboardVerticalOffset and topInset. When it unmounts, it calls onThreadDismount, which clears the stored thread here.
import { Text } from "react-native";
import { SafeAreaView } from "react-native-safe-area-context";
import { Stack } from "expo-router";
import { useHeaderHeight } from "expo-router/react-navigation";
import { MessageComposer, MessageList, Thread } from "stream-chat-expo";
import { useAppContext } from "../../../../contexts/AppContext";
export default function ThreadScreen() {
const { thread, setThread } = useAppContext();
const headerHeight = useHeaderHeight();
if (!thread) {
return (
<SafeAreaView>
<Text>Loading chat ...</Text>
</SafeAreaView>
);
}
return (
<>
<Stack.Screen options={{ title: "Thread" }} />
<Thread
keyboardVerticalOffset={headerHeight}
onThreadDismount={() => setThread(undefined)}
thread={thread}
topInset={headerHeight}
>
<MessageList />
<MessageComposer />
</Thread>
</>
);
}Checkpoint: long press a message, choose "Thread Reply", and the Thread screen opens with the parent message, its own message list, and its own composer. Sending a reply keeps you in the thread.


Step 9 - Theming
So far you've used the SDK's default look. Theming in the Expo SDK is a plain object of React Native styles that is deep-merged with the defaults, so you only declare the keys you want to change. The DeepPartial<Theme> type keeps those keys type-checked.
Add a theme object to ChatWrapper and pass it to OverlayProvider through its value prop:
import type { DeepPartial, Theme } from "stream-chat-expo";
// ...rest of the code
const chatTheme: DeepPartial<Theme> = {
semantics: {
chatBgOutgoing: "#81c784", // darker green - your own message bubbles
},
messageList: {
container: {
backgroundColor: "#c8e6c9", // light green - message list background
},
},
};
export const ChatWrapper = ({ children }: PropsWithChildren) => {
// ...existing chatClient logic
return (
<OverlayProvider value={{ style: chatTheme }}>
<Chat client={chatClient}>{children}</Chat>
</OverlayProvider>
);
};semantics is the SDK's color token layer. Name every token you want recolored - overriding an upstream token such as accentPrimary does not cascade to the leaves.
Checkpoint: open a channel - the message list sits on a light green background and your own messages are a darker green. Messages from other people keep the SDK's default bubble color, because chatBgOutgoing only recolors your side; its mirror token is chatBgIncoming.


Read more about theming, including dark mode, in our theming documentation.
Step 10 - Customization
Theming changes tokens. To replace an actual view, use WithComponents and pass an overrides object - everything you don't name keeps its default.
import { WithComponents } from "stream-chat-expo";
const overrides = { MessageItemView: MyCustomMessage };
<WithComponents overrides={overrides}>
<Channel channel={channel}>
<MessageList />
<MessageComposer />
</Channel>
</WithComponents>;WithComponents reads its overrides once, when it mounts, so declare the object outside of your components, as above.
WithComponents supports nesting - inner overrides merge over outer ones, so the closest provider wins. This lets you set app-wide defaults near the root and narrow overrides deeper in the tree (e.g. different components inside a thread screen).
10.1 - Customize the channel list
The ChannelList is essentially a FlatList of channels.
To customize the channel list item, override the ChannelPreview component using WithComponents. The default is ChannelPreviewView.
Objective: Highlight unread channels while keeping the default preview UI
Let's start by creating a custom list item component, which returns the default UI component ChannelPreviewView.
import {
ChannelPreviewView,
WithComponents,
type ChannelPreviewViewProps,
} from "stream-chat-expo";
// ...rest of the code
const CustomListItem = (props: ChannelPreviewViewProps) => {
return <ChannelPreviewView {...props} />;
};
const overrides = { ChannelPreview: CustomListItem };
export default function ChannelListScreen() {
const router = useRouter();
const { client } = useChatContext();
const { setChannel } = useAppContext();
// ...existing paginator logic
return (
<>
<Stack.Screen options={{ title: "Channels" }} />
<WithComponents overrides={overrides}>
<ChannelList
onSelect={(channel) => {
setChannel(channel);
router.push({
pathname: "/channel/[cid]",
params: { cid: channel.cid },
});
}}
paginator={paginator}
/>
</WithComponents>
</>
);
}The unread count of a channel arrives in the unread prop of the preview. We will use it to wrap unread channels in a light green background, and leave read channels as they are. The default preview has a transparent background, so the wrapper shows through.
import { StyleSheet, View } from "react-native";
// ...rest of the code
const CustomListItem = (props: ChannelPreviewViewProps) => {
const { unread } = props;
return (
<View style={unread ? styles.unreadContainer : undefined}>
<ChannelPreviewView {...props} />
</View>
);
};
const styles = StyleSheet.create({
unreadContainer: {
backgroundColor: "#c8e6c9", // light green
},
});Similarly, along with customizing the entire list item component, you can also override individual components within the list item, for example, ChannelPreviewStatus, ChannelPreviewAvatar, ChannelPreviewMessage, and ChannelPreviewUnreadCount by adding them to the overrides object. You can use the channel preview parts table to find out which components you can customize.


10.2 - Customize the message list
All components within the MessageList and MessageComposer can be customized using WithComponents.
Objective: Replace the Default Message UI with a Custom Component
The most common use case of customizing the MessageList is to have a custom UI for the message. You can do so by overriding MessageItemView via WithComponents as shown below.
import { WithComponents } from "stream-chat-expo";
// ...rest of the code
const CustomMessage = () => {
return null;
};
const overrides = { MessageItemView: CustomMessage };
export default function ChannelScreen() {
// ...existing logic
return (
<>
<Stack.Screen options={{ title: "Channel" }} />
<WithComponents overrides={overrides}>
<Channel
channel={channel}
keyboardVerticalOffset={headerHeight}
topInset={headerHeight}
>
<MessageList
onThreadSelect={(thread) => {
setThread(thread);
router.push({
pathname: "/channel/[cid]/thread/[messageId]",
params: {
cid: channel.cid,
messageId: thread.id,
},
});
}}
/>
<MessageComposer />
</Channel>
</WithComponents>
</>
);
}Now that we have configured the component, let's render the message on the UI. You can access the message object from the MessageContext. The MessageContext also gives you access to a boolean isMyMessage which you can use to style the message UI conditionally.
You can also access plenty of other useful properties and callbacks from this context, such as
setQuotedMessage,handleReaction, andonLongPress. Please check the MessageContext documentation for the full list.
import { useCallback } from "react";
import { Pressable, StyleSheet } from "react-native";
import type { GestureResponderEvent } from "react-native";
import { useMessageContext } from "stream-chat-expo";
// ...rest of the code
const CustomMessage = () => {
const { contextMenuAnchorRef, isMyMessage, message, onLongPress } =
useMessageContext();
const handleLongPress = useCallback(
(event: GestureResponderEvent) => onLongPress({ event }),
[onLongPress],
);
return (
<Pressable
onLongPress={handleLongPress}
ref={contextMenuAnchorRef}
style={isMyMessage ? styles.myMessage : styles.message}
>
<Text>{message.text}</Text>
</Pressable>
);
};
const styles = StyleSheet.create({
message: {
alignSelf: "flex-start",
backgroundColor: "#ededed",
borderRadius: 10,
margin: 10,
padding: 10,
width: "70%",
},
myMessage: {
alignSelf: "flex-end",
backgroundColor: "#ADD8E6",
borderRadius: 10,
margin: 10,
padding: 10,
width: "70%",
},
});This is a really simplified version of a custom message UI that displays only text. You can obviously add functionalities such as onPress, onLongPress handlers, and message actions according to your needs. Calling onLongPress from the context opens the message menu, which lines up with the view that holds contextMenuAnchorRef.
Generally, you wouldn't need to customize the entire message UI, but only the required parts such as MessageStatus, MessageAuthor, and MessageTimestamp. For this purpose, you can check the component customization guide to decide which key to pass in the overrides object. You can access MessageContext at every message-level component.
Checkpoint: unread channels in the list have a light green background behind the default preview, and messages render as your own bubbles - gray and left-aligned for others, blue and right-aligned for your own.


Verify the whole build
Step 10 replaced the message UI with a component that renders message.text and nothing else, so reactions, link previews and attachments do not show up on screen. Hand the SDK's default MessageItemView back to WithComponents before running the checks below:
import { MessageItemView } from "stream-chat-expo";
// ...rest of the code
const overrides = { MessageItemView };Your editor will flag CustomMessage as unused while the override is swapped out - that is expected.
npx expo run iosnpx expo run androidThen confirm the full loop on the running app: the channel list loads, tap a channel, send a message, long press it for reactions, open a thread and reply, and paste a YouTube link to watch it unfurl. Run it on both platforms if you support both - the composer and keyboard handling are the parts most likely to differ.


Image and file uploads, voice recordings, richer video playback and offline storage are opt-in - each needs an extra package. See the installation guide to add them, then re-run this verification with attachments included.
Customize further - cookbooks
For larger changes, Stream has full cookbooks. Each one is a short, self-contained recipe that swaps out a single piece of the chat UI.
Channel list
- Preview UI - the pattern for customizing previews and list behavior
- Channel backgrounds
- Pinned and archived channels
- Channel header
Messages and composer
- Custom message and custom message actions
- Custom attachments and custom reactions
- Custom composer and emoji suggestions
- Voice recordings and audio playback - voice recording in the composer
- Livestream message list
Theming
- Theming - the full theming model, including dark mode
- Replacing the icon set and localization
- Providers and context hooks and overriding components
Beyond the basics
- Thread list UI and the threads view
- AI components - streaming AI responses in a channel
- Location sharing and flagging, muting, blocking and bans
- Read state, unread and receipts, keyboard and insets, and accessibility
- Performance
We have also demonstrated the power of the SDK by building open-source clones of popular chat applications such as WhatsApp, Slack, and iMessage. The source code for all of them is in the react-native-samples repository.
Troubleshooting
stream project is not initialized- CLI onboarding not run. Rungetstream initin the project directory first.- The app crashes or shows a native module error in Expo Go -
stream-chat-expoships native code and does not run in Expo Go. Build a development build withnpx expo run iosornpx expo run android. - A red screen says
Cannot read property 'useState' of nullas soon asChatWrappermounts - the project holds two copies of React. Checkls node_modules/stream-chat-expo/node_modules: areactfolder there means npm installed React 18 for the SDK's Markdown dependency. Removenode_modulesandpackage-lock.json, then install again withnpx expo install stream-chat-expo stream-chat -- --legacy-peer-deps, as in Step 0. - Stuck on "Loading chat ..." - the client never connected. Check the Metro logs; an auth error usually means the API key and token belong to different apps, and a websocket error usually means the device or emulator has no working internet connection.
token is invalid/ auth error - token minted for a different app, or expired. Re-mint withgetstream token <user-id>and confirm the API key matches.process.env.EXPO_PUBLIC_STREAM_API_KEYis undefined - Expo inlinesEXPO_PUBLIC_*variables at bundle time. Restart the dev server aftergetstream env --target expowrites.env.- Channel list is empty, no errors - the user has no channels. Seed one with
getstream api GetOrCreateChannel(Step 3), or create one in the dashboard with Chat Explorer. If you're using the built-in credentials, remove themembersfilter from thefiltersobject. - A route 404s or the app opens a blank screen - the Expo Router entry point is missing. Set
"main": "expo-router/entry"inpackage.jsonand confirm the file lives underapp/. - The channel list starts under the header on iOS - the native header is see-through on iOS 26. Set
headerTransparent: falsein thescreenOptionsof theStack, as in Step 2. - The status bar icons are invisible on Android - the icons are light on a light header. Render
<StatusBar style="auto" />fromexpo-status-barinapp/_layout.tsx, as in Step 2. [Worklets] Mismatch between JavaScript code version and Worklets Babel plugin version- a stale Metro transform cache, not a missing plugin. Metro's cache lives in your system temp directory and is shared across projects, and the worklets plugin version is not part of its cache key, so a fresh project can pick up entries transformed by an older version of the plugin. Restart withnpx expo start --clear. Check withnpm ls react-native-workletsthat the project really does resolve a single copy.- Metro fails on some other worklets or Reanimated error - check that the Babel plugin is being applied. Expo SDK 54+ adds
"react-native-worklets/plugin"automatically whenreact-native-workletsis installed, so most projects need nobabel.config.jsat all. If you do have one, make sure it still extendsbabel-preset-expo, then restart withnpx expo start --clear. - Gestures, swipes, or the message menu don't respond - the app root must be wrapped in
GestureHandlerRootView, as in Step 2. - Metro logs lines such as
expo-haptics is not installed- in development builds, the SDK logs which optional package is missing. Install the package to turn its feature on, as the installation guide describes, or ignore the line. - Errors about the old architecture - the SDK is New Architecture only. See the requirements in Installation.
- Stale code after an edit - clear the bundler cache with
npx expo start --clear, and rebuild the development build after any native dependency change. - Crash mentioning safe area or gesture handler - provider order is wrong.
SafeAreaProvideris outermost, thenGestureHandlerRootView, then the Stream providers. - Thread screen opens empty -
threadwas never set. ConfirmonThreadSelectcallssetThread(thread)before navigating. - Theme has no effect - the theme goes on
OverlayProviderasvalue={{ style: chatTheme }}. A barevalue={chatTheme}is ignored. Keep the theme object defined outside the component so it isn't recreated on every render. - One theme key does nothing while the others work - at runtime, an unknown key is ignored without an error. Keep the
DeepPartial<Theme>annotation, so TypeScript flags a typo in your editor. Colors live undersemantics, and each leaf token has to be named explicitly. - A custom component never renders -
WithComponentsonly applies to its descendants. It has to wrap the component that renders the overridden view. - The keyboard covers the composer - pass
useHeaderHeight()to bothkeyboardVerticalOffsetandtopInsetonChannel. - TypeScript errors on your own custom data - the field is not declared in
custom-types.d.ts, or the file is outsideincludeintsconfig.json.
More platform-specific fixes live in the troubleshooting guide.
Next steps
- Push notifications - React Native push setup
- Offline support - cache channels and messages locally so the app works without a connection
- AI chat experiences - add an AI assistant to a channel with streaming responses: AI components
- Moderation - AI-powered content moderation for spam, profanity, and images
- Video and audio calls - the Video React Native SDK integrates with chat
- Design resources - download our free chat interface UI kit
- More platforms - the iOS, Android, and React Native CLI tutorials
- Sample code - the ExpoMessaging sample app that ships with the SDK
Pricing is flexible with multiple tiers, including a free maker plan for hobby projects and small companies.
Final Thoughts
In this chat app tutorial, we built a fully functioning Expo messaging app with our SDK's component library. We started with the polished defaults, then customized them with a theme object and scoped component overrides - all with minimal code changes.
Both the chat SDK for React Native and the API have plenty of features available to support more advanced use-cases such as push notifications, content moderation, rich messages, and more.
For more information read the React Native SDK Overview documentation, or review Stream's API documentation if you want to build a more complex chat application.
Machine-readable resources
For AI agents and coding assistants working with this SDK:
- CLI + skills:
curl -fsSL https://getstream.io/cli.sh | bash, thengetstream skillsandgetstream skills stream-react-nativefor the React Native pack. (Alternative:npx skills add GetStream/agent-skills -s stream.) - Provisioning:
getstream init(auth + create/select org & app) ->getstream env --target expo(writesEXPO_PUBLIC_STREAM_API_KEYto.env) ->getstream token <user-id>(mint a token) - Data & config from the CLI:
getstream api <Endpoint> --request '{...}'for users, channels, and messages - React Native integration skill: invoke
/stream-react-nativein your agent for Expo and React Native CLI setup patterns;/stream-docssearches live SDK docs with citations - Docs index for LLMs:
https://getstream.io/chat/docs/sdk/react-native/llms.txt - Markdown endpoints: append
.mdto any docs URL for a clean, token-efficient version - Source of truth for APIs: the SDK repository - check the installed version's source rather than assuming APIs from training data

