Multimodal Attachments
Let users send images, audio, video, and documents to the agent from a React Native app.
You have a working chat and want users to attach files (images, PDFs, audio, video) that the agent can see and respond to. On React Native, files come from the native document picker through Expo modules. By the end of this guide, your chat can pick files, show them before sending, and send them with the message.
Install the Expo modules
Attachments use expo-document-picker to pick files and expo-file-system to read them. Both are optional peer dependencies of @copilotkit/react-native:
npx expo install expo-document-picker expo-file-systemOn a bare React Native app, Expo modules need the expo package set up first. See Expo's guide to installing Expo modules.
The attachment APIs come from the package root, @copilotkit/react-native, not from /headless.
expo-file-system 19 and later: pass your own reader
The default reader calls readAsStringAsync from the main expo-file-system entry. From expo-file-system 19.0.0 (Expo SDK 54), that method moved to expo-file-system/legacy, and the old import throws when called. Every file then fails with upload-failed. To see your version, run npm ls expo-file-system. On 19 or later, read the file yourself in onUpload:
import * as FileSystem from "expo-file-system/legacy";
const attachments = {
enabled: true,
onUpload: async (file: NativeFileInput) => ({
type: "data" as const,
value: await FileSystem.readAsStringAsync(file.uri, {
encoding: FileSystem.EncodingType.Base64,
}),
mimeType: file.mimeType,
}),
};NativeFileInput is a type export of @copilotkit/react-native. Pass this object as the attachments prop in the samples below.
Quick start
Pass attachments to the root CopilotChat. It draws no UI. It adds the attachment state to useCopilotChatContext, which your own chat UI reads:
import { useState } from "react";
import { Image, Pressable, Text, TextInput, View } from "react-native";
import { CopilotChat, useCopilotChatContext } from "@copilotkit/react-native";
function Composer() {
const { attachments, openPicker, removeAttachment, submitMessage, isRunning } =
useCopilotChatContext();
const [text, setText] = useState("");
return (
<View style={{ padding: 8, gap: 8 }}>
<View style={{ flexDirection: "row", gap: 8 }}>
{attachments.map((attachment) => (
<Pressable key={attachment.id} onPress={() => removeAttachment(attachment.id)}>
{attachment.type === "image" && attachment.source.type === "data" ? (
<Image
source={{ uri: `data:${attachment.source.mimeType};base64,${attachment.source.value}` }}
style={{ width: 48, height: 48, borderRadius: 8 }}
/>
) : (
<Text>{attachment.status === "uploading" ? "Uploading..." : attachment.filename}</Text>
)}
</Pressable>
))}
</View>
<View style={{ flexDirection: "row", gap: 8 }}>
<Pressable onPress={openPicker}>
<Text>Attach</Text>
</Pressable>
<TextInput
style={{ flex: 1, borderWidth: 1, borderRadius: 8, padding: 8 }}
value={text}
onChangeText={setText}
placeholder="Type a message..."
/>
<Pressable
disabled={isRunning}
onPress={() => {
void submitMessage(text);
setText("");
}}
>
<Text>Send</Text>
</Pressable>
</View>
</View>
);
}
export function ChatScreen() {
return (
<CopilotChat agentId="default" attachments={{ enabled: true }}>
{/* Your message list goes here. */}
<Composer />
</CopilotChat>
);
}Tap Attach, pick a photo, type a question, and tap Send. The thumbnail clears when the message goes out, and the agent answers about the photo.
submitMessage does the sending work for you:
- It refuses to send while a file is still uploading.
- It takes the ready attachments off the queue.
- It adds a user message whose
contentis a list of parts: your text, then one part per file. - It runs the agent.
CopilotPopup and CopilotSidebar take the same attachments prop and pass it to the chat inside them. The rendered CopilotChat from /components does not support attachments.
Configuration
attachments takes a NativeAttachmentsConfig:
<CopilotChat
attachments={{
enabled: true,
// Omit `accept` to allow all file types (default: "*/*").
accept: "image/*,application/pdf",
maxSize: 10 * 1024 * 1024, // 10MB (default: 20MB)
}}
>
<Composer />
</CopilotChat>| Option | Type | Default | Description |
|---|---|---|---|
enabled | boolean | none | Turn attachments on. |
accept | string | "*/*" | MIME filter for the picker, such as "image/*" or "image/*,application/pdf". |
maxSize | number | 20 * 1024 * 1024 | Maximum file size in bytes. |
onUpload | (file: NativeFileInput) => AttachmentUploadResult | Promise<...> | none | Custom upload handler. See Custom upload handler. |
onUploadFailed | (error) => void | none | Called when a file fails validation or upload. See Handling upload errors. |
The web maxConcurrentUploads option doesn't exist here. Files picked together upload one after another.
NativeFileInput takes the place of the web File object. It has uri (a local file:// URI), name, size in bytes, and mimeType.
Supported file types
Each attachment gets a modality from its MIME type:
| Modality | MIME types | AI support |
|---|---|---|
| Image | image/* | Supported by most vision-capable models |
| Audio | audio/* | Model-dependent |
| Video | video/* | Model-dependent |
| Document | Everything else | Sent as file content. Model support varies |
Not all models support all modalities. For the details, see your model provider's docs. If the agent run fails, the onError callback on CopilotChat receives the error.
Custom upload handler
By default, the file is read as base64 with expo-file-system and sent inline in the message. On expo-file-system 19 or later, you need your own reader for that (see the warning above). For large files, upload them to your own storage and send a URL instead.
onUpload receives the NativeFileInput and returns an AttachmentUploadResult: { type: "data", value, mimeType } for inline base64, or { type: "url", value, mimeType? } for a hosted file.
<CopilotChat
attachments={{
enabled: true,
onUpload: async (file) => {
const body = new FormData();
// React Native's FormData takes a { uri, name, type } object for a file.
body.append("file", { uri: file.uri, name: file.name, type: file.mimeType } as any);
const res = await fetch("https://your-api.example.com/upload", { method: "POST", body });
const { url } = await res.json();
return {
type: "url",
value: url,
mimeType: file.mimeType,
metadata: { uploadedBy: currentUserId },
};
},
}}
>
<Composer />
</CopilotChat>metadata is optional. It is merged into the content part that the agent receives. The filename is always added for you.
Handling upload errors
Use onUploadFailed to react when a file is rejected or its upload fails, for example with an alert:
import { Alert } from "react-native";
<CopilotChat
attachments={{
enabled: true,
accept: "image/*",
maxSize: 5 * 1024 * 1024,
onUploadFailed: (error) => {
// error.reason: "file-too-large" | "invalid-type" | "upload-failed"
// error.file: the NativeFileInput
Alert.alert("Can't attach file", error.message);
},
}}
>
<Composer />
</CopilotChat>| Reason | When it fires |
|---|---|
invalid-type | The file doesn't match the accept filter. |
file-too-large | The file is bigger than maxSize. |
upload-failed | Your onUpload threw, or the default base64 read failed. |
Without CopilotChat
To manage attachments in your own composer, call useAttachments directly. It returns attachments, enabled, openPicker, processFiles, removeAttachment, and consumeAttachments:
import { useAttachments } from "@copilotkit/react-native";
const { attachments, openPicker, consumeAttachments } = useAttachments({
config: { enabled: true, accept: "image/*" },
});When you send, call consumeAttachments() to take the ready files off the queue. Build the message content from them yourself: a { type: "text", text } part, then one part per attachment with its type and source. Then call agent.addMessage and copilotkit.runAgent({ agent }). processFiles takes files from a source other than the picker, such as a camera library.
How it works
When a user attaches files and sends a message, CopilotKit:
- Reads each file, with the default base64 reader or your
onUploadhandler. - Builds a list of content parts: text, plus one part per attachment.
- Adds the message to the agent with
content: [{ type: "text", ... }, { type: "image", source: ... }, ...]. - Sends it to your agent over AG-UI, which forwards it to the model.
The parts follow the standard AG-UI content schema, so any AG-UI agent can receive them.
For every option, see the useAttachments reference.
How is this guide?