---
title: "useConfigureSuggestions"
description: "React hook for configuring chat suggestions"
---

## Overview

`useConfigureSuggestions` is a React hook that 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 automatically registered on mount and removed on unmount. When the configuration changes, suggestions are reloaded automatically.

## Signature

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

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

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

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

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`).
</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="ReadonlyArray<unknown>">
  Optional dependency array. When any value in this array changes, suggestions
  are reloaded. This is useful for dynamic suggestions that depend on external
  state.
</PropertyReference>

## Usage

### Static Suggestions

```tsx
function WelcomeSuggestions() {
  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",
  });

  return null;
}
```

### Dynamic Suggestions

```tsx
function SmartSuggestions() {
  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",
  });

  return null;
}
```

### Dynamic Suggestions with Dependencies

```tsx
function ContextualSuggestions() {
  const [topic, setTopic] = useState("general");

  useConfigureSuggestions(
    {
      instructions: `Generate suggestions related to the topic: ${topic}`,
      maxSuggestions: 3,
    },
    [topic],
  );

  return (
    <select value={topic} onChange={(e) => setTopic(e.target.value)}>
      <option value="general">General</option>
      <option value="technical">Technical</option>
      <option value="business">Business</option>
    </select>
  );
}
```

### Conditionally Disabling Suggestions

```tsx
function ConditionalSuggestions({ enabled }: { enabled: boolean }) {
  useConfigureSuggestions(
    enabled
      ? {
          suggestions: [{ title: "Help", message: "I need help" }],
        }
      : null,
  );

  return null;
}
```

### Targeting a Specific Agent

```tsx
function AgentSpecificSuggestions() {
  useConfigureSuggestions({
    instructions: "Suggest data analysis tasks the user can perform.",
    maxSuggestions: 4,
    providerAgentId: "analyst",
    consumerAgentId: "analyst",
    available: "always",
  });

  return null;
}
```

## Behavior

- **Automatic Registration**: The configuration is registered with the core on mount and removed on unmount. This ensures clean lifecycle management.
- **Change Detection**: The hook serializes the configuration to JSON for comparison. If the serialized value changes, the old config is removed and the new one is registered, triggering a reload.
- **Dependency Tracking**: When a `deps` array is provided, any change in its values 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"` will remove any previously registered configuration and produce no suggestions.
- **isLoading Normalization**: For static suggestions, the `isLoading` field defaults to `false` if not explicitly provided.

## Related

- [`useSuggestions`](/reference/hooks/useSuggestions) -- Read and interact with configured suggestions
