Reference / hooks

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;

Parameters

optionsUseSuggestionsOptions

Optional configuration object for the hook.

agentIdstring
Default: ""default""

ID of the agent whose suggestions to retrieve. If omitted, falls back to the agent ID from the nearest CopilotChatConfigurationProvider, or "default".

Return Value

resultUseSuggestionsResult

Object containing the current suggestions and control functions.

suggestionsSuggestion[]

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.

reloadSuggestions() => 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.

clearSuggestions() => void

Clears all current suggestions for the resolved agent.

isLoadingboolean

Whether suggestions are currently being generated or loaded.

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

2087950ee