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

<Callout type="info">
  Re-exported from `@copilotkit/react-core/v2`. It is identical to the [React (V2) `useConfigureSuggestions`](/reference/v2/hooks/useConfigureSuggestions); only the import path differs.
</Callout>

The configuration is automatically registered on mount and removed on unmount. When the configuration changes, suggestions are reloaded automatically. To read and show the suggestions, use [`useSuggestions`](/reference/react-native/hooks/useSuggestions).

## Signature [#signature]

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

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 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 are available. Options:

  - `"before-first-message"`: before any message is sent.
  - `"after-first-message"`: after the first message (the dynamic default).
  - `"always"`: always.
  - `"disabled"`: off.
</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`: the short display title.
  - `message: string`: the message to send when the user selects it.
  - `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 [#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
import { useState } from "react";
import { Text, TouchableOpacity, View } from "react-native";

const TOPICS = ["general", "technical", "business"];

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

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

  return (
    <View style={{ flexDirection: "row", gap: 8 }}>
      {TOPICS.map((value) => (
        <TouchableOpacity key={value} onPress={() => setTopic(value)}>
          <Text style={{ fontWeight: topic === value ? "700" : "400" }}>
            {value}
          </Text>
        </TouchableOpacity>
      ))}
    </View>
  );
}
```

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