useSuggestions

Overview

useSuggestions is a React hook that provides access to the current chat suggestions for a given agent. It subscribes to suggestion changes and automatically re-renders when suggestions are updated, cleared, or reloaded.

<Callout type="info"> Re-exported from `@copilotkit/react-core/v2`. It is identical to the [React (V2) `useSuggestions`](/reference/v2/hooks/useSuggestions); only the import path differs. </Callout>

Suggestions are configured via useConfigureSuggestions and can be either static (predefined) or dynamic (generated by the agent).

Signature

tsx

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;

Parameters

<PropertyReference name="options" type="UseSuggestionsOptions"> Optional configuration object for the hook. <PropertyReference name="agentId" type="string" default='"default"'> ID of the agent whose suggestions to retrieve. If omitted, falls back to the agent ID from the nearest `CopilotChatConfigurationProvider`, or `"default"`. </PropertyReference> </PropertyReference>

Return Value

<PropertyReference name="result" type="UseSuggestionsResult"> Object containing the current suggestions and control functions. <PropertyReference name="suggestions" type="Suggestion[]"> Array of current suggestions. Each `Suggestion` contains: `title: string`, the short display title for the suggestion; `message: string`, the message content to send when the suggestion is selected; and `isLoading: boolean`, whether this suggestion is still being generated. </PropertyReference> <PropertyReference name="reloadSuggestions" type="() => void"> Triggers a reload of the suggestions for the resolved agent. For dynamic suggestions, this re-invokes the generation process. The `isLoading` state updates automatically via subscription events. </PropertyReference> <PropertyReference name="clearSuggestions" type="() => void"> Clears all current suggestions for the resolved agent. </PropertyReference> <PropertyReference name="isLoading" type="boolean"> Whether suggestions are currently being generated or loaded. </PropertyReference> </PropertyReference>

Usage

Basic Usage

tsx

import { Text, View } from "react-native";

function SuggestionsList() {
  const { suggestions, isLoading } = useSuggestions();

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

  return (
    <View>
      {suggestions.map((suggestion, i) => (
        <View key={i}>
          <Text style={{ fontWeight: "bold" }}>{suggestion.title}</Text>
          <Text>{suggestion.message}</Text>
        </View>
      ))}
    </View>
  );
}

With Reload and Clear Controls

tsx

import { Text, TouchableOpacity, View } from "react-native";

function SuggestionsPanel() {
  const { suggestions, reloadSuggestions, clearSuggestions, isLoading } =
    useSuggestions();

  return (
    <View>
      <View>
        <TouchableOpacity onPress={reloadSuggestions} disabled={isLoading}>
          <Text>Refresh</Text>
        </TouchableOpacity>
        <TouchableOpacity onPress={clearSuggestions}>
          <Text>Clear</Text>
        </TouchableOpacity>
      </View>
      {suggestions.map((suggestion, i) => (
        <TouchableOpacity key={i} disabled={suggestion.isLoading}>
          <Text>{suggestion.title}</Text>
        </TouchableOpacity>
      ))}
    </View>
  );
}

Targeting a Specific Agent

tsx

import { Text, View } from "react-native";

function AgentSuggestions() {
  const { suggestions } = useSuggestions({ agentId: "support-agent" });

  return (
    <View>
      <Text>Support Agent Suggestions</Text>
      {suggestions.map((s, i) => (
        <Text key={i}>{s.title}</Text>
      ))}
    </View>
  );
}

Behavior

Automatic Subscription: The hook subscribes to suggestion change events on the core instance and re-renders whenever suggestions are added, removed, or updated for the resolved agent.
Agent Resolution: The agentId is resolved in the following order of precedence: explicit agentId option, agentId from the nearest CopilotChatConfigurationProvider, then the default agent ID ("default").
Loading State: isLoading becomes true when a dynamic suggestion reload begins and returns to false when generation completes.
Initial State: On mount, the hook synchronously reads the current suggestions from the core instance, so there is no unnecessary loading flash for static suggestions.

useConfigureSuggestions: configure static or dynamic suggestions
React (V2) reference