CopilotKit

useThreads

React hook for listing, managing, and syncing conversation threads with useThreads. Rename, archive, delete, and paginate threads with realtime updates via WebSocket.

Overview

useThreads is a React hook for managing conversation threads in CopilotKit Intelligence. It fetches the thread list for a given agent, keeps it synchronized in realtime via WebSocket, and exposes mutation methods for renaming, archiving, and deleting threads.

Thread persistence runs in CopilotKit Intelligence, which is accessed with a publicLicenseKey. That key is not yet supported on React Native (see CopilotKitProvider), so useThreads is documented here for API parity but is not yet usable on React Native.

Re-exported from @copilotkit/react-core/v2, identical to the React (V2) useThreads. The only difference is the import path.

Threads are sorted by most recently updated first. The hook supports cursor-based pagination when a limit is provided.

Signature

import { useThreads } from "@copilotkit/react-native";

function useThreads(input: UseThreadsInput): UseThreadsResult

Parameters

Prop

Type

Return Value

Prop

Type

Usage

ThreadList.tsx
import { useThreads } from "@copilotkit/react-native"; 
import { FlatList, Text, TouchableOpacity, View } from "react-native";

function ThreadList() {
  const {
    threads,
    isLoading,
    renameThread,
    archiveThread,
    deleteThread,
  } = useThreads({ agentId: "my-agent" }); 

  if (isLoading) {
    return (
      <View>
        <Text>Loading threads...</Text>
      </View>
    );
  }

  return (
    <FlatList
      data={threads}
      keyExtractor={(thread) => thread.id}
      renderItem={({ item: thread }) => (
        <View>
          <Text>{thread.name ?? "Untitled"}</Text>
          <TouchableOpacity onPress={() => renameThread(thread.id, "New name")}>
            <Text>Rename</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => archiveThread(thread.id)}>
            <Text>Archive</Text>
          </TouchableOpacity>
          <TouchableOpacity onPress={() => deleteThread(thread.id)}>
            <Text>Delete</Text>
          </TouchableOpacity>
        </View>
      )}
    />
  );
}

Behavior

  • On mount, fetches the thread list and establishes a realtime WebSocket subscription.
  • Thread creates, renames, archives, and deletes from any client are reflected immediately without polling.
  • All mutation methods use pessimistic updates: the UI updates only after the server confirms the operation via WebSocket, not immediately on dispatch. Promises resolve on confirmation (15-second timeout) and reject on failure.
  • The error state updates with the most recent error from any operation.
  • The threads array stays sorted by updatedAt descending (most recent first).
  • New threads are automatically named by the LLM after their first run (a short title of 2 to 5 words). This is configurable via generateThreadNames on the runtime.

Next steps