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 on the Enterprise Intelligence Platform. 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 on the Enterprise Intelligence Platform, 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