useSuggestions & useConfigureSuggestions

Hooks for managing and configuring AI-generated conversation suggestions

Overview

CopilotKit provides two hooks for working with conversation suggestions:

• useSuggestions: Access and control suggestions for an agent
• useConfigureSuggestions: Configure how suggestions are generated

Suggestions help users start or continue conversations by providing contextually relevant prompts.

useSuggestions

Access the current suggestions for an agent and control suggestion loading.

Usage

import { useSuggestions } from "@copilotkit/react";

function SuggestionList() {
  const { 
    suggestions, 
    isLoading, 
    reloadSuggestions, 
    clearSuggestions 
  } = useSuggestions();
  
  if (isLoading) return <div>Loading suggestions...</div>;
  
  return (
    <div>
      {suggestions.map((suggestion, idx) => (
        <button key={idx} onClick={() => console.log(suggestion.message)}>
          {suggestion.title}
        </button>
      ))}
    </div>
  );
}

Type Signature

function useSuggestions(options?: UseSuggestionsOptions): UseSuggestionsResult

interface UseSuggestionsOptions {
  agentId?: string;
}

interface UseSuggestionsResult {
  suggestions: Suggestion[];
  isLoading: boolean;
  reloadSuggestions: () => void;
  clearSuggestions: () => void;
}

interface Suggestion {
  title: string;
  message: string;
  isLoading: boolean;
}

Parameters

options.agentId · string

The ID of the agent to get suggestions for. If not specified, uses the agent from CopilotChatConfiguration context, or falls back to the default agent.

const { suggestions } = useSuggestions({ agentId: "research-agent" });

Return Value

suggestions · Suggestion[]

Array of suggestion objects, each containing:

Show Suggestion Properties

title · string

Short title or label for the suggestion

message · string

The full message text that will be sent when the suggestion is used

isLoading · boolean

Whether this specific suggestion is still being generated

isLoading · boolean

Whether suggestions are currently being loaded or generated

reloadSuggestions · () => void

Function to trigger a reload of suggestions for the agent

<button onClick={reloadSuggestions}>Refresh Suggestions</button>

clearSuggestions · () => void

Function to clear all current suggestions for the agent

<button onClick={clearSuggestions}>Clear Suggestions</button>

Examples

Basic Suggestion Pills

import { useSuggestions } from "@copilotkit/react";

function SuggestionPills({ onSelectSuggestion }) {
  const { suggestions, isLoading } = useSuggestions();
  
  if (isLoading) {
    return <div className="suggestions-loading">Generating suggestions...</div>;
  }
  
  if (suggestions.length === 0) {
    return null;
  }
  
  return (
    <div className="suggestion-pills">
      {suggestions.map((suggestion, idx) => (
        <button
          key={idx}
          className="suggestion-pill"
          onClick={() => onSelectSuggestion(suggestion.message)}
        >
          {suggestion.title}
        </button>
      ))}
    </div>
  );
}

Suggestion Cards with Details

import { useSuggestions } from "@copilotkit/react";

function SuggestionCards({ onSelect }) {
  const { suggestions, reloadSuggestions } = useSuggestions();
  
  return (
    <div className="suggestion-cards">
      <div className="header">
        <h3>Suggested Questions</h3>
        <button onClick={reloadSuggestions}>↻ Refresh</button>
      </div>
      
      <div className="cards">
        {suggestions.map((suggestion, idx) => (
          <div
            key={idx}
            className="suggestion-card"
            onClick={() => onSelect(suggestion.message)}
          >
            <div className="title">{suggestion.title}</div>
            <div className="preview">{suggestion.message}</div>
          </div>
        ))}
      </div>
    </div>
  );
}

Loading State Per Suggestion

import { useSuggestions } from "@copilotkit/react";

function SmartSuggestions() {
  const { suggestions } = useSuggestions();
  
  return (
    <div className="suggestions">
      {suggestions.map((suggestion, idx) => (
        <div key={idx} className="suggestion">
          {suggestion.isLoading ? (
            <div className="skeleton">Loading...</div>
          ) : (
            <button>{suggestion.title}</button>
          )}
        </div>
      ))}
    </div>
  );
}

Multi-Agent Suggestions

import { useSuggestions } from "@copilotkit/react";

function MultiAgentSuggestions() {
  const research = useSuggestions({ agentId: "research" });
  const support = useSuggestions({ agentId: "support" });
  
  return (
    <div>
      <section>
        <h3>Research Suggestions</h3>
        {research.suggestions.map((s, i) => (
          <button key={i}>{s.title}</button>
        ))}
      </section>
      
      <section>
        <h3>Support Suggestions</h3>
        {support.suggestions.map((s, i) => (
          <button key={i}>{s.title}</button>
        ))}
      </section>
    </div>
  );
}

---

useConfigureSuggestions

Configure how suggestions are generated for agents, either statically or dynamically via AI.

Usage

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

function App() {
  // Static suggestions
  useConfigureSuggestions({
    suggestions: [
      {
        title: "Get Started",
        message: "How do I get started with this app?",
      },
      {
        title: "Features",
        message: "What are the main features?",
      },
    ],
  });
  
  return <YourApp />;
}

Type Signature

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

Configuration Types

There are two types of suggestion configurations:

1. Static Suggestions

Provide a fixed list of suggestions:

type StaticSuggestionsConfig = {
  suggestions: Array<{
    title: string;
    message: string;
  }>;
  available?: SuggestionAvailability;
  consumerAgentId?: string;
}

2. Dynamic Suggestions

Let AI generate suggestions based on instructions:

type DynamicSuggestionsConfig = {
  instructions: string;
  minSuggestions?: number;
  maxSuggestions?: number;
  available?: SuggestionAvailability;
  providerAgentId?: string;
  consumerAgentId?: string;
}

Parameters

config · SuggestionsConfigInput | null | undefined

Configuration object for suggestions. Can be null or undefined to disable suggestions.

Show Static Configuration

suggestions · Array<{ title: string; message: string }> · required

Array of suggestion objects with title and message.

suggestions: [
  { title: "Help", message: "How can I use this?" },
  { title: "Examples", message: "Show me some examples" },
]

available · SuggestionAvailability · default: "'before-first-message'"

When to show suggestions:

• "before-first-message": Only before user sends first message (default for static)
• "after-first-message": Only after first message
• "always": Always show suggestions
• "disabled": Disable suggestions

available: "always"

consumerAgentId · string · default: "'*'"

Which agent(s) should use these suggestions. Use "*" for all agents, or specify an agent ID.

consumerAgentId: "chat-agent"

Show Dynamic Configuration

instructions · string · required

Instructions for the AI to generate relevant suggestions.

instructions: "Generate helpful questions about the current document"

minSuggestions · number · default: "1"

Minimum number of suggestions to generate.

maxSuggestions · number · default: "3"

Maximum number of suggestions to generate.

available · SuggestionAvailability · default: "'after-first-message'"

When to show suggestions (same options as static, but default is "after-first-message" for dynamic).

providerAgentId · string · default: "'default'"

Which agent should generate the suggestions.

consumerAgentId · string · default: "'*'"

Which agent(s) should use these suggestions.

deps · ReadonlyArray<unknown>

Optional dependency array. When dependencies change, suggestions are reloaded.

useConfigureSuggestions(config, [documentId, userRole]);

Examples

Static Welcome Suggestions

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

function WelcomeScreen() {
  useConfigureSuggestions({
    suggestions: [
      {
        title: "👋 Getting Started",
        message: "How do I get started with this application?",
      },
      {
        title: "📚 Documentation",
        message: "Where can I find the documentation?",
      },
      {
        title: "❓ Help",
        message: "What can this assistant help me with?",
      },
    ],
    available: "before-first-message",
  });
  
  return <div>Welcome!</div>;
}

Dynamic Context-Aware Suggestions

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

function DocumentEditor({ document }) {
  useConfigureSuggestions({
    instructions: `Generate suggestions based on the current document titled "${document.title}". 
    Suggest questions about editing, formatting, or understanding the content.`,
    minSuggestions: 2,
    maxSuggestions: 4,
    available: "always",
  }, [document.id]); // Reload when document changes
  
  return <Editor document={document} />;
}

Role-Based Suggestions

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

function Dashboard({ user }) {
  const suggestions = user.role === "admin" 
    ? [
        { title: "User Management", message: "Show me user management options" },
        { title: "System Settings", message: "Access system settings" },
        { title: "Analytics", message: "Show system analytics" },
      ]
    : [
        { title: "My Profile", message: "View my profile" },
        { title: "Help", message: "How do I use this dashboard?" },
      ];
  
  useConfigureSuggestions({
    suggestions,
    available: "always",
  }, [user.role]);
  
  return <DashboardContent />;
}

Agent-Specific Suggestions

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

function App() {
  // Research agent suggestions
  useConfigureSuggestions({
    instructions: "Generate research-related questions about papers, citations, and methodology",
    consumerAgentId: "research-agent",
    available: "always",
  });
  
  // Support agent suggestions
  useConfigureSuggestions({
    suggestions: [
      { title: "Report Issue", message: "I need to report a technical issue" },
      { title: "Account Help", message: "Help with my account" },
    ],
    consumerAgentId: "support-agent",
    available: "before-first-message",
  });
  
  return <YourApp />;
}

Conditional Suggestions

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

function ProductPage({ product, isAuthenticated }) {
  useConfigureSuggestions(
    isAuthenticated
      ? {
          instructions: `Generate suggestions about this product: ${product.name}. 
          Include questions about purchasing, specifications, and comparisons.`,
          available: "always",
        }
      : {
          suggestions: [
            { title: "Sign In", message: "How do I sign in?" },
            { title: "Learn More", message: "Tell me more about this product" },
          ],
          available: "before-first-message",
        },
    [product.id, isAuthenticated]
  );
  
  return <ProductDetails product={product} />;
}

Disable Suggestions

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

function RestrictedArea({ showSuggestions }) {
  useConfigureSuggestions(
    showSuggestions
      ? { suggestions: [{ title: "Help", message: "Help me" }] }
      : null, // Disable suggestions
    [showSuggestions]
  );
  
  return <div>Restricted content</div>;
}

Multi-Layer Configuration

You can configure suggestions at different levels:

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

function App() {
  // Global suggestions for all agents
  useConfigureSuggestions({
    suggestions: [
      { title: "Help", message: "How can I get help?" },
    ],
    consumerAgentId: "*", // All agents
    available: "before-first-message",
  });
  
  return <YourApp />;
}

function SpecificFeature() {
  // Feature-specific suggestions
  useConfigureSuggestions({
    instructions: "Generate suggestions about this specific feature",
    available: "after-first-message",
  });
  
  return <FeatureContent />;
}

Suggestion Availability

available · SuggestionAvailability

Controls when suggestions are shown:

• "before-first-message": Show only when the conversation is empty (default for static)
• "after-first-message": Show only after the user has sent at least one message (default for dynamic)
• "always": Show suggestions at all times
• "disabled": Don’t show suggestions

Use Cases

Onboarding

Welcome new users with helpful starter questions to guide them through your app.

Context Awareness

Dynamically generate suggestions based on current page, document, or user activity.

Discovery

Help users discover features and capabilities they might not know about.

Workflow Acceleration

Provide quick access to common tasks and frequently asked questions.

Conversation Continuity

Suggest natural follow-up questions to keep conversations flowing.

Notes

Static vs Dynamic: Use static suggestions for consistent, well-known options (like welcome messages). Use dynamic suggestions when you want AI to generate contextually relevant prompts based on current application state.

When using useConfigureSuggestions with dynamic values, include appropriate dependencies in the deps array to ensure suggestions reload when context changes.

Multiple useConfigureSuggestions calls can coexist. Each configuration is tracked independently and can target different agents via consumerAgentId.

Best Practices

1. Keep titles short: Suggestion titles should be concise (2-5 words)
2. Make messages actionable: Messages should be complete, actionable prompts
3. Context matters: For dynamic suggestions, provide clear instructions that reference current context
4. Limit quantity: Don’t overwhelm users with too many suggestions (3-5 is ideal)
5. Update appropriately: Reload suggestions when context changes significantly

Related

• CopilotKitProvider - Root provider configuration
• useAgent - Access agent instances