useConfigureSuggestions

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.

Signature

tsx

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

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" shows suggestions before any messages are sent; "after-first-message" shows suggestions after the first message (the dynamic default); "always" always shows suggestions; "disabled" turns suggestions 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

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 for the suggestion; `message: string`, the message content to send when selected; and `isLoading?: boolean`, an 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

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

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.

useSuggestions: read and interact with configured suggestions
React (V2) reference