# useConfigureSuggestions

> Vue 3 composable for configuring chat suggestions

## Overview [#overview]

`useConfigureSuggestions` registers a suggestions configuration with the CopilotKit core. It supports two modes: **static** suggestions (a fixed list) and **dynamic** suggestions (generated by the agent based on instructions).

The configuration is registered while the composable's reactive scope is active and removed automatically on scope cleanup (component unmount). Because the config is tracked reactively, changing it (or any value in the optional `deps` watch sources) reloads suggestions automatically without manual teardown. To read the suggestions in your UI, use [`useSuggestions`](/reference/vue/hooks/useSuggestions).

<Callout type="info">
  `useConfigureSuggestions` 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 reactive scope is bound to the component lifecycle.
</Callout>

## Signature [#signature]

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

function useConfigureSuggestions(
  config: SuggestionsConfigInput | null | undefined,
  deps?: WatchSource<unknown>[],
): void;
```

## Parameters [#parameters]

<PropertyReference name="config" type="SuggestionsConfigInput | null | undefined">
  The suggestions configuration. Pass `null` or `undefined` to disable suggestions. Can be either a `DynamicSuggestionsConfig` or a `StaticSuggestionsConfigInput`.

### Dynamic Configuration [#dynamic-configuration]

Used when suggestions should be generated by the agent at runtime.

<PropertyReference name="instructions" type="string" required>
  A prompt or instructions for the model to generate suggestions. This is the
  key that distinguishes a dynamic config from a static one.
</PropertyReference>

<PropertyReference name="minSuggestions" type="number" default="1">
  The minimum number of suggestions to generate.
</PropertyReference>

<PropertyReference name="maxSuggestions" type="number" default="3">
  The maximum number of suggestions to generate.
</PropertyReference>

<PropertyReference
  name="available"
  type="SuggestionAvailability"
  default='"after-first-message"'
>
  When the suggestions should be available. Options:

  - `"before-first-message"`: show suggestions before any messages are sent.
  - `"after-first-message"`: show suggestions after the first message (default for dynamic).
  - `"always"`: always show suggestions.
  - `"disabled"`: disable suggestions.
</PropertyReference>

<PropertyReference name="providerAgentId" type="string" default='"default"'>
  The agent ID of the provider that generates the suggestions.
</PropertyReference>

<PropertyReference name="consumerAgentId" type="string" default='"*"'>
  The agent ID of the consumer that displays the suggestions. Defaults to `"*"`
  (all agents).
</PropertyReference>

### Static Configuration [#static-configuration]

Used when suggestions are a predefined list.

<PropertyReference name="suggestions" type="StaticSuggestionInput[]" required>
  Array of suggestion objects. Each suggestion has:

  - `title: string`: short display title for the suggestion.
  - `message: string`: the message content to send when selected.
  - `isLoading?: boolean`: optional loading state (defaults to `false`).
  - `className?: string`: optional CSS class applied to the suggestion pill.
</PropertyReference>

<PropertyReference
  name="available"
  type="SuggestionAvailability"
  default='"before-first-message"'
>
  When the suggestions should be available. Same options as dynamic
  configuration.
</PropertyReference>

<PropertyReference name="consumerAgentId" type="string" default='"*"'>
  The agent ID of the consumer that displays the suggestions. Defaults to `"*"` (all agents).
</PropertyReference>
</PropertyReference>

<PropertyReference name="deps" type="WatchSource<unknown>[]">
  Optional array of Vue watch sources (refs, computeds, or getter functions).
  When any of these sources changes, suggestions are reloaded. This is useful for
  dynamic suggestions that depend on external reactive state.
</PropertyReference>

## Usage [#usage]

### Static Suggestions [#static-suggestions]

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

useConfigureSuggestions({
  suggestions: [
    { title: "Get started", message: "Help me get started with my project" },
    { title: "Show examples", message: "Show me some example use cases" },
    { title: "Documentation", message: "Where can I find the documentation?" },
  ],
  available: "before-first-message",
});
</script>

<template>
  <div>Suggestions configured</div>
</template>
```

### Dynamic Suggestions [#dynamic-suggestions]

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

useConfigureSuggestions({
  instructions:
    "Suggest follow-up questions based on the conversation so far. " +
    "Focus on actionable next steps the user might want to take.",
  maxSuggestions: 3,
  minSuggestions: 1,
  available: "after-first-message",
});
</script>

<template>
  <div>Smart suggestions enabled</div>
</template>
```

### Dynamic Suggestions with Reactive Dependencies [#dynamic-suggestions-with-reactive-dependencies]

Pass watch sources as the second argument so suggestions reload whenever the
underlying reactive state changes.

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

const reloadKey = ref(0);

// `deps` reloads suggestions from the same config whenever a watch source
// changes. To change `instructions`, remount the component.
useConfigureSuggestions(
  {
    instructions: "Suggest concise next steps based on the current conversation",
    maxSuggestions: 3,
  },
  [reloadKey],
);
</script>

<template>
  <button @click="reloadKey++">Refresh suggestions</button>
</template>
```

<Callout type="info">
  The `config` object is captured once from the surrounding scope when the
  composable runs. The composable serializes and watches the config. If the
  reactive contents of the config change, the registration runs again. A config
  built from plain (non-reactive) locals never changes, so in practice the
  composable reads it one time. Use `deps` to *reload* (regenerate) suggestions from that captured
  config. To change the `instructions` themselves at runtime (for example to
  inject a reactive topic), remount the component that calls
  `useConfigureSuggestions` -- e.g. give it a `:key` that changes -- so the
  composable re-runs with the new values.
</Callout>

### Conditionally Disabling Suggestions [#conditionally-disabling-suggestions]

Pass `null` (or a config with `available: "disabled"`) to skip registering a
configuration.

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

const props = defineProps<{ enabled: boolean }>();

useConfigureSuggestions(
  props.enabled
    ? { suggestions: [{ title: "Help", message: "I need help" }] }
    : null,
);
</script>

<template>
  <div>Conditional suggestions</div>
</template>
```

<Callout type="info">
  Like the dynamic config above, the `enabled` branch is evaluated once when the
  composable runs. Flipping `props.enabled` later does not re-register or remove
  the configuration. To turn suggestions on or off at runtime, conditionally
  render the component that calls `useConfigureSuggestions` (for example with
  `v-if`) so the composable re-runs and its previous configuration is removed on
  cleanup.
</Callout>

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

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

useConfigureSuggestions({
  instructions: "Suggest data analysis tasks the user can perform.",
  maxSuggestions: 4,
  providerAgentId: "analyst",
  consumerAgentId: "analyst",
  available: "always",
});
</script>

<template>
  <div>Agent-specific suggestions</div>
</template>
```

## Behavior [#behavior]

- **Scope lifecycle**: The configuration is registered with the core via `addSuggestionsConfig` while the composable's reactive scope is active and removed via `removeSuggestionsConfig` on scope cleanup (component unmount). No manual cleanup is required.
- **Reactive change detection**: The hook serializes the normalized configuration to JSON for comparison. When the serialized value changes, the registration is updated and a reload is triggered.
- **Dependency tracking**: When a `deps` array of watch sources is provided, any change in those sources triggers a suggestion reload, even if the serialized config itself has not changed.
- **Config discrimination**: The hook distinguishes between dynamic and static configs by checking for the presence of the `instructions` property. If `instructions` is present, it is treated as a dynamic config.
- **Disabled state**: Passing `null`, `undefined`, or a config with `available: "disabled"` removes any previously registered configuration and produces no suggestions.
- **isLoading normalization**: For static suggestions, the `isLoading` field defaults to `false` if not explicitly provided.
- **Consumer resolution**: A config with `consumerAgentId` of `"*"` (or unset) is treated as global and applies to all agents; otherwise it targets the named agent. The resolved consumer falls back to the chat configuration's `agentId`, then to the default agent ID.
- **Reload while running**: Global reloads are deferred for any agent that is currently running and flushed once that run finishes, so suggestions are not reloaded mid-run.
