AI Integrations

The AI UI components are built for AI-first React Native apps. Paired with our real-time Chat API, they make it easier to render LLM responses (ChatGPT, Gemini, Anthropic, or your backend) with rich UI: markdown, syntax highlighting, tables, thinking indicators, charts, and more.

Core components include:

• StreamingMessageView - renders text/markdown/code in real time with a typewriter effect
• ComposerView - a fully featured prompt composer with attachments and speech input
• SpeechToTextButton - a reusable button that records voice input and streams the recognized transcript back into your UI
• AITypingIndicatorView - a component that can display different states of the LLM (thinking, checking external sources, etc)

We’ll keep adding components. If you want to see something added, open an issue.

You can find a complete ChatGPT clone sample that uses these components here.

Installation

Install @stream-io/chat-react-native-ai and peer dependencies:

yarn add @stream-io/chat-react-native-ai react-native-reanimated react-native-worklets react-native-gesture-handler react-native-svg victory-native @shopify/react-native-skia @babel/plugin-proposal-export-namespace-from

Add the required babel plugins to babel.config.js:

module.exports = {
  presets: ["module:@react-native/babel-preset"],
  plugins: [
    // ... rest of your @babel plugins
    "@babel/plugin-proposal-export-namespace-from",
    // react-native-worklets/plugin has to be the last one
    "react-native-worklets/plugin",
  ],
};

To enable speech-to-text, add the required capabilities:

iOS

Within Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>$(PRODUCT_NAME) would like to access your microphone to capture your voice.</string>
<key>NSSpeechRecognitionUsageDescription</key>
<string>$(PRODUCT_NAME) would like to access speech recognition to transcribe your voice.</string>

Choose any permission strings you want.

Android

Within android/app/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO" />

Expo

If you use managed Expo, the config plugin can add these permissions for you.

You can do this by adding it to your app.json/app.config.[js|ts] file like so:

"plugins": [
      // ... rest of your plugins
      [
        "@stream-io/chat-react-native-ai",
        {
          "dictationMicrophoneUsageDescription": "$(PRODUCT_NAME) would like to access your microphone to capture your voice.",
          "dictationSpeechRecognitionUsageDescription": "$(PRODUCT_NAME) would like to access speech recognition to transcribe your voice."
        }
      ]
    ],

If you use bare Expo, follow the manual iOS/Android steps above.

Optional features

Optional dependencies enable extra features.

Media Picker

Media picker lets users select images or take photos.

The SDK supports two libraries:

react-native-image-picker

This RN CLI library is meant to be used in vanilla React Native projects.

To install it, you can run:

yarn add react-native-image-picker

For image capture, add these permissions:

Info.plist:

<key>NSCameraUsageDescription</key>
<string>$(PRODUCT_NAME) would like to use your camera to share an image in a message.</string>

AndroidManifest.xml:

<uses-permission android:name="android.permission.CAMERA" />

Respectively.

expo-image-picker

This Expo library is meant to be used in Expo projects.

To install it, you can run:

npx expo install expo-image-picker

Then, you can refer to their documentation about adding permissions and add the photosPermission and cameraPermission fields.

Clipboard

Clipboard support lets users copy code blocks from rendered markdown.

The SDK has built-in support for 2 libraries that allow you to achieve this:

• @react-native-clipboard/clipboard (for RN CLI apps)
• expo-clipboard (for Expo apps)

Components

All components integrate with the React Native Chat SDK. See the developer guide to get started.

Wrap them in StreamTheme so theming is applied. Place it high in your component tree.

StreamingMessageView

StreamingMessageView renders markdown efficiently with syntax highlighting for common languages. It supports standard markdown: tables, inline code, headings, lists, etc.

It uses a letter-by-letter typewriter animation similar to ChatGPT.

Example

Example:

const markdownText = ```
# Heading

some text

## Another heading
```;

<StreamingMessageView
  text={markdownText}
  letterInterval={5} // every 5ms
  renderingLetterCount={3} // render 3 letters at a time
/>;

AITypingIndicatorView

The AITypingIndicatorView is used to represent different states of the LLM, such as Thinking, Checking External Sources and so on, depending on the states you've defined on your backend. The only thing that needs to be passed to the component is the text property, which will then be displayed with a shimmering animation.

Example

<AITypingIndicatorView text={"Thinking of an answer..."} />

ComposerView

ComposerView provides a modern composer with attachments, a bottom sheet, speech-to-text, and a send button.

Example

import { Alert } from "react-native";
import { Flag, PhotoIcon } from "stream-chat-react-native";
import { useSafeAreaInsets } from "react-native-safe-area-context";

const options = [
  {
    title: "Create Image",
    subtitle: "Visualize anything",
    action: () => Alert.alert("Pressed on Create Image !"),
    Icon: PhotoIcon,
  },
  {
    title: "Thinking",
    subtitle: "Think longer for better answers",
    action: () => Alert.alert("Pressed on Thinking !"),
    Icon: Flag,
  },
];

const insets = useSafeAreaInsets();

<ComposerView
  onSendMessage={sendMessage}
  bottomSheetOptions={options}
  bottomSheetInsets={insets}
/>;

SpeechToTextButton

The SpeechToTextButton turns voice input into text using native implementations of the iOS and Android speech frameworks, respectively. When tapped it asks for microphone access, records audio and forwards the recognized transcript to the ComposerState directly.

It uses the useDictation hook under the hood, which can also be used without the button as well for voice transcription purposes outside of the button.

It takes a single property named options that has the following keys:

const options = {
  language: 'de-DE', // set the language to german
  intermediateResults: false, // disable intermediate results and only use the final results
  silenceTimeoutMs: 3500 // set the silence timeout to 3.5 seconds
}
<SpeechToTextButton options={options} />

The SpeechToTextButton is already integrated within the ComposerView, however feel free to use it elsewhere as well.

Theming

Each one of the components in the SDK is fully theme-compatible. The StreamTheme provider takes care of this for you.

In order to modify the theme, you may refer to our full fledged theme object as seen here.

Example

In the example below, we introduce a dark color scheme through the theming system.

const customTheme = {
  colors: colorScheme === 'dark'
    ? {
      accent_blue: '#4C9DFF',
      accent_red: '#FF636E',
      black: '#FFFFFF',
      code_block: '#1E1E22',
      grey: '#A1A1AA',
      grey_neutral: '#C5C5C8',
      grey_dark: '#71717A',
      grey_gainsboro: '#3F3F46',
      grey_whisper: '#27272F',
      overlay: '#000000CC',
      transparent: 'transparent',
      white: '#050509',
      white_smoke: '#121214',
      shimmer: '#FFFFFF',
    } : {}
}

<StreamTheme style={customTheme}>{children}</StreamTheme>

Best practices

• Keep AI components wrapped in StreamTheme for consistent styling.
• Stream tokens progressively to StreamingMessageView to avoid large re-renders.
• Gate speech-to-text behind explicit permissions and user consent.
• Use a single source of truth for LLM state to drive typing indicators.
• Test markdown rendering with long responses and code blocks.

Mark assistant messages with ai_generated

The Chat SDK treats a reply from your AI bot like any other message. To render it with StreamingMessageView and its character-by-character animation, the app needs a way to tell AI replies apart from the rest.

The convention used by the AI components, the sample apps and the Stream backend SDKs is a custom field, ai_generated: true, set by the backend when it creates the assistant's placeholder message:

const { message } = await channel.sendMessage({
  text: "",
  user_id: botId,
  ai_generated: true,
});

placeholder = channel.send_message(
    MessageRequest(text="", user_id=bot_id, custom={"ai_generated": True}),
).data.message

In React Native the field arrives as message.ai_generated. Read it in a function and pass that function to Chat as isMessageAIGenerated:

import type { LocalMessage } from "stream-chat";
import { Chat } from "stream-chat-react-native";

// Defined once, outside any component.
const isMessageAIGenerated = (message: LocalMessage) => !!message.ai_generated;

const App = () => (
  <Chat client={client} isMessageAIGenerated={isMessageAIGenerated}>
    {/* ... */}
  </Chat>
);

With TypeScript, message.ai_generated only compiles once you declare it on CustomMessageData, as described in TypeScript. Declare generating there too:

import type { DefaultMessageData } from "stream-chat-react-native";

declare module "stream-chat" {
  interface CustomMessageData extends DefaultMessageData {
    ai_generated?: boolean;
    generating?: boolean;
  }
}

The flag matters in three places:

• Rendering. For AI messages, MessageContent renders the StreamingMessageView component in place of MessageTextContainer. This is what gives the reply its character-by-character animation. The SDK ships a default StreamingMessageView. To render the markdown view from this package instead, override it through WithComponents as shown in the SDK integration. A message without the flag renders as a regular text bubble that jumps to the new text on every update.
• The "Edited" label. Every update the backend makes to the text counts as an edit. MessageFooter hides the label for AI messages, so there's nothing to configure.
• Your backend. The bot usually listens for new messages in the channel. Checking ai_generated lets it skip its own replies instead of answering itself.

Two details make the flag silently stop working:

• Set it on Chat, not Channel. Channel accepts an isMessageAIGenerated prop too, but always replaces it with the value from the Chat context, so a function set only on Channel is ignored. The SDK also isn't guaranteed to pick up a new function on a later render, so define it once, outside your components, and base it only on the message.
• Keep 'ai_text' in messageContentOrder. AI messages render their text through the 'ai_text' entry, and the regular 'text' entry skips them. If you pass your own messageContentOrder to Channel, include 'ai_text', or AI replies render without any text.

The second field the backend sets is generating: true on every interim update and false on the final one. Neither StreamingMessageView, the SDK's default or the one from this package, reads it. The animation follows the text alone: the view shows whatever text the message has when it mounts, then types out only what's added after that. That's why stored replies don't replay the animation when the user scrolls back to them, and why someone who opens the channel mid-reply sees the text so far at once. generating arrives with every message update, so read it in your own components when they need to know whether a reply is still in progress.

Drive the AI indicator from events

Before the first token arrives, the LLM can spend a while thinking or calling tools, and the message is still empty. The backend reports what it's doing with ai_indicator.* custom events on the channel, and they reach the app as regular stream-chat channel events:

useAIState(channel) from stream-chat-react-native listens for the first two and returns the current state as aiState. The SDK's own AITypingIndicatorView and the MessageComposer stop button are built on it, and the SDK integration shows how to drive this package's AITypingIndicatorView with it.

Both packages export an AITypingIndicatorView and a StreamingMessageView, with different props. The ones from stream-chat-react-native read the AI state and the message themselves, while the ones from @stream-io/chat-react-native-ai take the text to show. The sample app imports useAIState and AIStates from the first and both views from the second.

Compare aiState with the AIStates constants. The "SDK default" column is what the SDK's AITypingIndicatorView (if you render it) and MessageComposer show:

A typical reply sends AI_STATE_THINKING right after the placeholder, AI_STATE_EXTERNAL_SOURCES while a tool call runs, AI_STATE_GENERATING with the first token, and ai_indicator.clear once the final text is stored.

A few things about useAIState and the defaults aren't obvious:

• It only knows about events it has seen. Every call starts at AI_STATE_IDLE when its component mounts and changes only when an event arrives. It goes back to idle on ai_indicator.clear and when the connection drops, but not when you pass it a different channel: it subscribes to the new channel and keeps the old state until that channel sends an event. The sample app remounts its channel screen with key={channel.id}, which also resets the state. Do the same if one screen shows several channels in turn.
• An error isn't followed by a clear. The Stream Chat AI SDK and the Stream Chat LangChain SDK send AI_STATE_ERROR and then write the error into the message without sending ai_indicator.clear, so aiState stays AI_STATE_ERROR until the next reply starts. Treat it as a final state.
• Tool calls hide the default UI. The SDK's AITypingIndicatorView and stop button only react to AI_STATE_THINKING and AI_STATE_GENERATING. While a tool runs, both the indicator and the stop button disappear. If your agent uses tools, show this package's AITypingIndicatorView for AIStates.ExternalSources too and, with ComposerView, include that state in isGenerating.
• Match tool calls with AIStates.ExternalSources. The AIState type in stream-chat lists AI_STATE_CHECKING_SOURCES, but the backend SDKs send AI_STATE_EXTERNAL_SOURCES, which is the value of AIStates.ExternalSources. The type accepts any string, so a comparison with the wrong literal compiles and never matches.

useAIState returns only the state. When you also need the id of the reply, for example to show a cursor or a stop control on that message, listen with channel.on yourself. A channel's listeners only receive that channel's events, so no cid check is needed:

import { useEffect, useState } from "react";
import type { AIState, Channel } from "stream-chat";
import { AIStates } from "stream-chat-react-native";

export const useAIIndicator = (channel?: Channel) => {
  const [aiState, setAIState] = useState<AIState>(AIStates.Idle);
  const [messageId, setMessageId] = useState<string>();

  useEffect(() => {
    // Start from idle whenever the channel changes.
    setAIState(AIStates.Idle);
    setMessageId(undefined);
    if (!channel) return;

    const update = channel.on("ai_indicator.update", (event) => {
      setAIState(event.ai_state ?? AIStates.Idle);
      setMessageId(event.message_id);
    });
    const clear = channel.on("ai_indicator.clear", () => {
      setAIState(AIStates.Idle);
      setMessageId(undefined);
    });

    return () => {
      update.unsubscribe();
      clear.unsubscribe();
    };
  }, [channel]);

  return { aiState, messageId };
};

Render this package's AITypingIndicatorView for the states you want to show, between MessageList and the composer, as in the SDK integration. The sample app has a complete channel screen.

Indicator events only reach clients that are connected when they're sent. They aren't stored or replayed, so a user who opens the channel halfway through a reply never gets the earlier AI_STATE_THINKING or AI_STATE_GENERATING: useAIState reports idle, and the default composer shows no stop button. Use them for the indicator only, and rely on the message's text and generating fields, which arrive with every message update, for the reply itself.

Let users stop the response

A long reply can take a while, and the user may already have what they need or see the model heading the wrong way. The default MessageComposer already handles this. While useAIState reports AI_STATE_THINKING or AI_STATE_GENERATING, it shows StopMessageStreamingButton in place of the send button, and a tap calls channel.stopAIResponse(). With this package's ComposerView, pass isGenerating and a stopGenerating callback that calls the same method, as shown in the SDK integration.

stopAIResponse() comes from stream-chat and sends an ai_indicator.stop event with no other fields. It doesn't change any state in the app. useAIState has no setter, so the stop button stays on screen until the backend sends ai_indicator.clear or a new ai_indicator.update.

The stop event names only the channel, not a message, so on the backend treat it as "stop whatever reply is in flight in this channel". Abort the LLM stream, then finish the same way a normal reply finishes: store the text generated so far with a regular partial update and generating: false, then send ai_indicator.clear. Skipping that final update leaves the message stuck in its last stored state, as described in the next section, and skipping the clear leaves the stop button on screen. The Stream Chat AI SDK and the Stream Chat LangChain SDK already listen for ai_indicator.stop and do this for you.

Use ephemeral updates while the response is streaming

The components above render whatever your backend writes into the assistant's message. A typical backend posts an empty placeholder message as the AI bot, then keeps updating it as the LLM streams tokens back. Each update reaches the app as a message.updated event, and StreamingMessageView animates the new text in.

How the backend sends those updates matters. A regular partial update (partialUpdateMessage) writes the message to the database on every call. A long reply flushed every few tokens turns into dozens or hundreds of writes, and with several conversations running at once you can quickly hit the rate limits for message updates.

For the updates sent while the response is still streaming, use ephemeralUpdateMessage instead:

• It accepts the same payload as a partial update (set, unset and the acting user).
• It sends the same message.updated event to everyone watching the channel, so the live typing in the app looks exactly the same.
• It doesn't store anything in the database, it only sends the event. Skipping the database write is what keeps high-frequency streaming from getting rate limited.

The last update must not be ephemeral. When the LLM finishes, send the complete text with a regular partial update and set generating to false. Ephemeral updates are never stored, so if the final one is ephemeral too, anyone who opens the channel later or relaunches the app loads the last stored version of the message: the empty placeholder, still marked as generating. The same applies to whatever else ends the stream, such as an error message or the user stopping the generation.

ephemeralUpdateMessage is available only on the server side. Call it from your backend, not from the React Native app. In Node.js it ships in stream-chat 9.27.0 and later, and every server-side SDK exposes an equivalent:

// While the LLM is streaming: send the latest text without storing it.
await client.ephemeralUpdateMessage(
  messageId,
  { set: { text, generating: true } },
  botId,
);

// Once the LLM has finished: store the final text.
await client.partialUpdateMessage(
  messageId,
  { set: { text, generating: false } },
  botId,
);

# While the LLM is streaming: send the latest text without storing it.
client.chat.ephemeral_message_update(
    id=message_id,
    set={"text": text, "generating": True},
    user_id=bot_id,
)

# Once the LLM has finished: store the final text.
client.chat.update_message_partial(
    id=message_id,
    set={"text": text, "generating": False},
    user_id=bot_id,
)

# While the LLM is streaming: send the latest text without storing it.
client.chat.ephemeral_message_update(message_id, Models::UpdateMessagePartialRequest.new(
  set: { 'text' => text, 'generating' => true },
  user_id: bot_id,
))

# Once the LLM has finished: store the final text.
client.chat.update_message_partial(message_id, Models::UpdateMessagePartialRequest.new(
  set: { 'text' => text, 'generating' => false },
  user_id: bot_id,
))

// While the LLM is streaming: send the latest text without storing it.
$client->ephemeralMessageUpdate($messageId, new Models\UpdateMessagePartialRequest(
    set: (object)["text" => $text, "generating" => true],
    userID: $botId,
));

// Once the LLM has finished: store the final text.
$client->updateMessagePartial($messageId, new Models\UpdateMessagePartialRequest(
    set: (object)["text" => $text, "generating" => false],
    userID: $botId,
));

// While the LLM is streaming: send the latest text without storing it.
_, err := client.Chat().EphemeralMessageUpdate(ctx, messageID, &getstream.EphemeralMessageUpdateRequest{
    Set: getstream.PtrTo(map[string]any{
        "text":       text,
        "generating": true,
    }),
    UserID: getstream.PtrTo(botID),
})

// Once the LLM has finished: store the final text.
_, err = client.Chat().UpdateMessagePartial(ctx, messageID, &getstream.UpdateMessagePartialRequest{
    Set: getstream.PtrTo(map[string]any{
        "text":       text,
        "generating": false,
    }),
    UserID: getstream.PtrTo(botID),
})

// While the LLM is streaming: send the latest text without storing it.
await chat.EphemeralMessageUpdateAsync(messageId, new UpdateMessagePartialRequest
{
    Set = new Dictionary<string, object>
    {
        { "text", text },
        { "generating", true },
    },
    UserID = botId,
});

// Once the LLM has finished: store the final text.
await chat.UpdateMessagePartialAsync(messageId, new UpdateMessagePartialRequest
{
    Set = new Dictionary<string, object>
    {
        { "text", text },
        { "generating", false },
    },
    UserID = botId,
});

Even ephemeral updates are delivered to every device watching the channel, so don't send one per token. Flushing every 20 or so chunks, or at most every 50 to 100 ms, keeps the typing smooth without wasting bandwidth. The AI message streaming guide covers the full backend flow, including throttling and the AI indicator events that drive AITypingIndicatorView.

If you use the Stream Chat AI SDK or the Stream Chat LangChain SDK on your backend, this is already handled for you: both send ephemeral updates while streaming and store the final text with a regular partial update.