# useSuggestions

> React hook for accessing chat suggestions

## Overview [#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`](/reference/hooks/useConfigureSuggestions) and can be either static (predefined) or dynamic (generated by the agent).

## Signature [#signature]

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;
```

## Parameters [#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`, then the `agentId` on `CopilotKitProvider`, then `"default"`.
  </PropertyReference>
</PropertyReference>

## Return Value [#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.
  - `className?: string`: optional CSS class name applied to the suggestion pill.
</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 [#usage]

### Basic 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 [#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 [#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 [#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`, the `agentId` on `CopilotKitProvider`, 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.
