Hooks

/**
 * Configure automatic chat suggestions generated by AI
 * @param config - Suggestion configuration with instructions and constraints
 * @param dependencies - Optional dependency array for re-registration
 * @experimental Interface may change in future versions
 */
function useCopilotChatSuggestions(
  config: UseCopilotChatSuggestionsConfiguration,
  dependencies?: any[]
): void;

interface UseCopilotChatSuggestionsConfiguration {
  /** Instructions for GPT to generate relevant suggestions */
  instructions: string;

  /** Minimum number of suggestions to generate (default: 1) */
  minSuggestions?: number;

  /** Maximum number of suggestions to generate (default: 3) */
  maxSuggestions?: number;

  /** Whether suggestions are available (default: "enabled") */
  available?: "enabled" | "disabled";

  /** Optional CSS class for suggestions container */
  className?: string;
}

import { CopilotPopup, useCopilotChatSuggestions } from "@copilotkit/react-ui";
import "@copilotkit/react-ui/styles.css";

function MyApp() {
  // Configure suggestions based on current context
  useCopilotChatSuggestions({
    instructions: "Suggest helpful questions the user might want to ask about their data analysis tasks.",
    minSuggestions: 2,
    maxSuggestions: 4,
  });

  return (
    <div>
      <DataAnalysisPanel />
      <CopilotPopup suggestions="auto" />
    </div>
  );
}

import { CopilotChat, useCopilotChatSuggestions } from "@copilotkit/react-ui";
import { useState } from "react";

function DocumentEditor() {
  const [currentDocument, setCurrentDocument] = useState<Document | null>(null);

  // Update suggestions when document changes
  useCopilotChatSuggestions(
    {
      instructions: currentDocument
        ? `Suggest relevant actions for editing a document titled "${currentDocument.title}" with ${currentDocument.wordCount} words. Suggest things like summarizing, improving clarity, checking grammar, or extracting key points.`
        : "Suggest general document editing tasks like creating a new document, opening a file, or learning about features.",
      minSuggestions: 3,
      maxSuggestions: 5,
    },
    [currentDocument?.id] // Re-register when document changes
  );

  return (
    <div className="editor-layout">
      <Editor document={currentDocument} onChange={setCurrentDocument} />
      <CopilotChat suggestions="auto" />
    </div>
  );
}

import { CopilotPopup, useCopilotChatSuggestions } from "@copilotkit/react-ui";

function ShoppingCart({ items }: { items: CartItem[] }) {
  const hasItems = items.length > 0;

  useCopilotChatSuggestions(
    {
      instructions: hasItems
        ? `User has ${items.length} items in cart. Suggest actions like applying discounts, checking out, or finding similar products.`
        : "Cart is empty. Suggest browsing categories, viewing deals, or searching for products.",
      minSuggestions: 2,
      maxSuggestions: 3,
      available: "enabled",
    },
    [items.length]
  );

  return (
    <div>
      <CartDisplay items={items} />
      <CopilotPopup suggestions="auto" />
    </div>
  );
}

import { CopilotChat, useCopilotChatSuggestions } from "@copilotkit/react-ui";

function RestrictedArea({ userRole }: { userRole: string }) {
  // Disable suggestions for certain user roles
  useCopilotChatSuggestions(
    {
      instructions: "Suggest general help topics.",
      available: userRole === "admin" ? "enabled" : "disabled",
    },
    [userRole]
  );

  return <CopilotChat suggestions="auto" />;
}

/**
 * Access chat context including labels, icons, and open state
 * @returns Chat context object
 * @throws Error if used outside ChatContextProvider
 */
function useChatContext(): ChatContext;

interface ChatContext {
  /** All label overrides with defaults applied */
  labels: Required<CopilotChatLabels>;

  /** All icon overrides with defaults applied */
  icons: Required<CopilotChatIcons>;

  /** Whether chat is currently open (for popup/sidebar) */
  open: boolean;

  /** Function to set open state */
  setOpen: (open: boolean) => void;
}

interface CopilotChatLabels {
  initial?: string | string[];
  title?: string;
  placeholder?: string;
  error?: string;
  stopGenerating?: string;
  regenerateResponse?: string;
  copyToClipboard?: string;
  thumbsUp?: string;
  thumbsDown?: string;
  copied?: string;
}

interface CopilotChatIcons {
  openIcon?: React.ReactNode;
  closeIcon?: React.ReactNode;
  headerCloseIcon?: React.ReactNode;
  sendIcon?: React.ReactNode;
  activityIcon?: React.ReactNode;
  spinnerIcon?: React.ReactNode;
  stopIcon?: React.ReactNode;
  regenerateIcon?: React.ReactNode;
  pushToTalkIcon?: React.ReactNode;
  copyIcon?: React.ReactNode;
  thumbsUpIcon?: React.ReactNode;
  thumbsDownIcon?: React.ReactNode;
  uploadIcon?: React.ReactNode;
}

import { useChatContext } from "@copilotkit/react-ui";

function CustomChatHeader() {
  const { labels, icons, open, setOpen } = useChatContext();

  return (
    <header className="chat-header">
      <h2>{labels.title}</h2>
      <button onClick={() => setOpen(!open)}>
        {open ? icons.closeIcon : icons.openIcon}
      </button>
    </header>
  );
}

import { useChatContext } from "@copilotkit/react-ui";

function CustomToggleButton() {
  const { open, setOpen, labels, icons } = useChatContext();

  return (
    <button
      onClick={() => setOpen(!open)}
      className={`toggle-btn ${open ? "open" : "closed"}`}
      aria-label={open ? "Close chat" : "Open chat"}
    >
      {open ? icons.closeIcon : icons.openIcon}
      <span>{open ? "Close" : labels.title}</span>
    </button>
  );
}

import { useChatContext } from "@copilotkit/react-ui";

function ChatStatusIndicator() {
  const { open, labels } = useChatContext();

  return (
    <div className="status-indicator">
      <div className={`status-dot ${open ? "active" : "inactive"}`} />
      <span>
        {labels.title} is {open ? "open" : "closed"}
      </span>
    </div>
  );
}

import { useChatContext, InputProps } from "@copilotkit/react-ui";
import { useState } from "react";

function CustomInputWithContext({ inProgress, onSend }: InputProps) {
  const { labels, icons } = useChatContext();
  const [text, setText] = useState("");

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (!text.trim() || inProgress) return;
    await onSend(text);
    setText("");
  };

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="text"
        value={text}
        onChange={(e) => setText(e.target.value)}
        placeholder={labels.placeholder}
        disabled={inProgress}
      />
      <button type="submit" disabled={!text.trim() || inProgress}>
        {icons.sendIcon}
      </button>
    </form>
  );
}

import { CopilotPopup, useChatContext } from "@copilotkit/react-ui";
import { useEffect } from "react";

function AppWithProgrammaticControl() {
  return (
    <CopilotPopup instructions="You are helpful.">
      <AppContent />
    </CopilotPopup>
  );
}

function AppContent() {
  const { setOpen } = useChatContext();

  // Open chat when user is inactive
  useEffect(() => {
    const timeout = setTimeout(() => {
      setOpen(true);
    }, 30000); // Open after 30 seconds

    return () => clearTimeout(timeout);
  }, [setOpen]);

  const handleHelpClick = () => {
    // Open chat when help button is clicked
    setOpen(true);
  };

  return (
    <div>
      <button onClick={handleHelpClick}>Need Help?</button>
      <YourAppContent />
    </div>
  );
}

/**
 * Provider for chat context - automatically used by chat components
 * @param props - Labels, icons, and open state
 * @returns Provider component wrapping children
 * @internal Typically not used directly by applications
 *
 * Note: ChatContextProvider and ChatContextProps are internal and not exported
 * from @copilotkit/react-ui. This documentation is provided for reference only.
 */
function ChatContextProvider(props: ChatContextProps): JSX.Element;

interface ChatContextProps {
  /** Label overrides */
  labels?: CopilotChatLabels;

  /** Icon overrides */
  icons?: CopilotChatIcons;

  /** Current open state */
  open: boolean;

  /** Function to update open state */
  setOpen: (open: boolean) => void;

  /** Child components */
  children?: React.ReactNode;
}

import { ChatContextProvider, useChatContext } from "@copilotkit/react-ui";
import { useState } from "react";

// Rarely needed - chat components provide this automatically
function ManualContextSetup() {
  const [open, setOpen] = useState(false);

  return (
    <ChatContextProvider
      open={open}
      setOpen={setOpen}
      labels={{
        title: "Custom Chat",
        placeholder: "Type here...",
      }}
      icons={{
        sendIcon: "→",
        closeIcon: "×",
      }}
    >
      <CustomChatImplementation />
    </ChatContextProvider>
  );
}

function CustomChatImplementation() {
  const context = useChatContext();
  // Build custom chat UI using context
  return <div>{/* Custom implementation */}</div>;
}