CopilotKit

useSuggestions

React hook for accessing chat suggestions

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.

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

Signature

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;

Parameters

Prop

Type

Return Value

Prop

Type

Usage

Basic Usage

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

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

  return (
    <ul>
      {suggestions.map((suggestion, i) => (
        <li key={i}>
          <strong>{suggestion.title}</strong>
          <p>{suggestion.message}</p>
        </li>
      ))}
    </ul>
  );
}

With Reload and Clear Controls

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

  return (
    <div>
      <div>
        <button onClick={reloadSuggestions} disabled={isLoading}>
          Refresh
        </button>
        <button onClick={clearSuggestions}>Clear</button>
      </div>
      {suggestions.map((suggestion, i) => (
        <button key={i} disabled={suggestion.isLoading}>
          {suggestion.title}
        </button>
      ))}
    </div>
  );
}

Targeting a Specific Agent

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

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

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.

Related