# useConfigureSuggestions

> React hook for configuring chat suggestions

## Overview [#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.

To read the suggestions and render your own pills, see [`useSuggestions`](/reference/hooks/useSuggestions). For suggestions in a chat UI, see [Prebuilt components](/prebuilt-components/chat).

## Signature [#signature]

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

function useConfigureSuggestions(
  config: SuggestionsConfigInput | null | undefined,
  deps?: ReadonlyArray<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 configuration 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 name 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="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 [#usage]

### Static Suggestions [#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 [#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 [#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 [#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 [#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 [#behavior]

- **Automatic Registration**: The configuration is registered with the core on mount and removed on unmount.
- **Change Detection**: The hook serializes the configuration to JSON for comparison. If the serialized value changes, the hook removes the old configuration and registers the new one. Then the suggestions reload.
- **Dependency Tracking**: When a `deps` array is provided, any change in its values triggers a suggestion reload, even if the serialized configuration itself has not changed.
- **Configuration Discrimination**: The hook distinguishes between dynamic and static configurations by checking for the presence of the `instructions` property. If `instructions` is present, it is treated as a dynamic configuration.
- **Disabled State**: Passing `null`, `undefined`, or a configuration 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.
