ContextQMD
Back to Copilotkit

useSuggestions

showcase/shell-docs/src/content/reference/vue/hooks/useSuggestions.mdx

1.61.16.5 KB
Original Source

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 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`. 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

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;

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

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

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

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

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

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

  • 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.