# useSuggestions

> Vue 3 composable for accessing chat suggestions

## Overview [#overview]

`useSuggestions` provides reactive access to the current chat suggestions for a given agent. It subscribes to suggestion changes on the CopilotKit core and updates its returned refs whenever suggestions are added, cleared, reloaded, or finish loading.

Suggestions are configured via [`useConfigureSuggestions`](/reference/vue/hooks/useConfigureSuggestions) and can be either static (a predefined list) or dynamic (generated by the agent).

<Callout type="info">
  `useSuggestions` must be called within a component that has access to the
  CopilotKit instance provided by [`CopilotKitProvider`](/reference/vue/components/CopilotKitProvider). Like all Vue
  composables, call it synchronously inside `<script setup>` or a `setup()`
  function so its subscription is bound to the component lifecycle and cleaned
  up automatically on unmount.
</Callout>

## Signature [#signature]

```ts
import { useSuggestions } from "@copilotkit/vue/v2";

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

## Parameters [#parameters]

<PropertyReference name="options" type="UseSuggestionsOptions">
  Optional configuration object for the composable.

  <PropertyReference name="agentId" type="MaybeRefOrGetter<string | undefined>" default='"default"'>
    ID of the agent whose suggestions to retrieve. Accepts a plain string, a
    `ref`, or a getter function, so the resolved agent can change reactively. If
    omitted (or resolving to `undefined`), it falls back to the `agentId` from
    the nearest chat configuration, then to the default agent ID (`"default"`).
  </PropertyReference>
</PropertyReference>

## Return Value [#return-value]

The composable returns an object of Vue refs and control functions. Because `suggestions` and `isLoading` are refs, access their `.value` in `<script setup>` (they unwrap automatically in `<template>`).

<PropertyReference name="result" type="UseSuggestionsResult">
  Object containing the reactive suggestions state and control functions.

<PropertyReference name="suggestions" type="Ref<Suggestion[]>">
  Reactive 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 individual suggestion is still being generated.
  - `className?: string`: optional CSS class applied to the suggestion pill.
</PropertyReference>

<PropertyReference name="isLoading" type="Ref<boolean>">
  Reactive flag indicating whether suggestions are currently being generated or
  loaded for the resolved agent.
</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` ref
  updates automatically via subscription events.
</PropertyReference>

  <PropertyReference name="clearSuggestions" type="() => void">
    Clears all current suggestions for the resolved agent.
  </PropertyReference>
</PropertyReference>

## Usage [#usage]

### Basic Usage [#basic-usage]

```vue
<script setup lang="ts">
import { useSuggestions } from "@copilotkit/vue/v2";

const { suggestions, isLoading } = useSuggestions();
</script>

<template>
  <div v-if="isLoading">Loading suggestions...</div>
  <ul v-else>
    <li v-for="(suggestion, i) in suggestions" :key="i">
      <strong>{{ suggestion.title }}</strong>
      <p>{{ suggestion.message }}</p>
    </li>
  </ul>
</template>
```

### With Reload and Clear Controls [#with-reload-and-clear-controls]

```vue
<script setup lang="ts">
import { useSuggestions } from "@copilotkit/vue/v2";

const { suggestions, reloadSuggestions, clearSuggestions, isLoading } =
  useSuggestions();
</script>

<template>
  <div>
    <div>
      <button :disabled="isLoading" @click="reloadSuggestions">Refresh</button>
      <button @click="clearSuggestions">Clear</button>
    </div>
    <button
      v-for="(suggestion, i) in suggestions"
      :key="i"
      :disabled="suggestion.isLoading"
    >
      {{ suggestion.title }}
    </button>
  </div>
</template>
```

### Targeting a Specific Agent [#targeting-a-specific-agent]

```vue
<script setup lang="ts">
import { useSuggestions } from "@copilotkit/vue/v2";

const { suggestions } = useSuggestions({ agentId: "support-agent" });
</script>

<template>
  <div>
    <h3>Support Agent Suggestions</h3>
    <div v-for="(s, i) in suggestions" :key="i">{{ s.title }}</div>
  </div>
</template>
```

### Reactive Agent ID [#reactive-agent-id]

Because `agentId` accepts a `ref` or getter, the composable re-resolves and re-subscribes whenever the source changes, swapping in the new agent's suggestions automatically.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useSuggestions } from "@copilotkit/vue/v2";

const activeAgentId = ref("default");

const { suggestions } = useSuggestions({ agentId: activeAgentId });
</script>

<template>
  <select v-model="activeAgentId">
    <option value="default">Default</option>
    <option value="support-agent">Support</option>
  </select>
  <div v-for="(s, i) in suggestions" :key="i">{{ s.title }}</div>
</template>
```

## Behavior [#behavior]

- **Reactive subscription**: The composable subscribes to suggestion events on the CopilotKit core (`onSuggestionsChanged`, `onSuggestionsStartedLoading`, `onSuggestionsFinishedLoading`, `onSuggestionsConfigChanged`) and updates its refs whenever suggestions are added, removed, updated, or change loading state for the resolved agent. The subscription is cleaned up automatically when the component unmounts.
- **Agent resolution**: The resolved agent ID is computed in this order of precedence: the `agentId` option (a string, ref, or getter), then the `agentId` from the nearest chat configuration, then the default agent ID (`"default"`).
- **Re-subscription on change**: When the resolved agent ID or the underlying CopilotKit instance changes, the composable re-reads the current suggestions and re-subscribes so events are scoped to the new agent.
- **Loading state**: `isLoading` becomes `true` when a dynamic suggestion reload begins and returns to `false` when generation completes.
- **Initial state**: On setup, the composable synchronously reads the current suggestions and loading state from the core instance, so there is no unnecessary loading flash for static suggestions.
