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.

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

Signature

tsx

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

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` -- Short display title for the suggestion. - `message: string` -- The message content to send when the suggestion is selected. - `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

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

tsx

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

tsx

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.

useConfigureSuggestions -- Configure static or dynamic suggestions