CopilotKit

useSuggestions

Vue 3 composable for accessing chat suggestions

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

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.

Signature

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

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult;

Parameters

Prop

Type

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

Prop

Type

Usage

Basic Usage

<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

<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

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

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

Related