assistant-ui logo/Docs

Suggestions

Display suggested prompts to help users get started with your assistant.

Suggestions are pre-defined prompts that help users discover what your assistant can do. They appear in the welcome screen and provide a quick way to start conversations.

Overview

The Suggestions API allows you to configure a list of suggested prompts that are displayed when the thread is empty. Users can click on a suggestion to either populate the composer or immediately send the message.

Quick Start

Configure suggestions using the Suggestions() API in your runtime provider:

import { useAui, Tools, Suggestions } from "@assistant-ui/react";
import { useChatRuntime } from "@assistant-ui/react-ai-sdk";

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();

  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
    suggestions: Suggestions([
      "What can you help me with?",
      "Tell me a joke",
      "Explain quantum computing",
    ]),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}

Suggestion Format

Suggestions can be provided as either strings or objects with title, label, and prompt:

Simple Strings

const aui = useAui({
  suggestions: Suggestions([
    "What's the weather today?",
    "Help me write an email",
    "Explain React hooks",
  ]),
});

Objects with Title and Description

For more detailed suggestions with separate display text and prompts:

const aui = useAui({
  suggestions: Suggestions([
    {
      title: "Weather",
      label: "in San Francisco",
      prompt: "What's the weather in San Francisco?",
    },
    {
      title: "React Hooks",
      label: "useState and useEffect",
      prompt: "Explain React hooks like useState and useEffect",
    },
    {
      title: "Travel Tips",
      label: "for Tokyo",
      prompt: "Give me travel tips for visiting Tokyo",
    },
  ]),
});

Displaying Suggestions

The default Thread component from the shadcn registry already includes suggestion rendering. The suggestions are displayed in the welcome screen when the thread is empty.

Customizing Suggestion Display

If you want to customize how suggestions are displayed, you can modify your Thread component. The idiomatic pattern is to wrap the suggestions in AuiIf so they only appear when the thread is empty:

import {
  ThreadPrimitive,
  SuggestionPrimitive,
  AuiIf,
} from "@assistant-ui/react";

const ThreadWelcome = () => {
  return (
    <AuiIf condition={(s) => s.thread.isEmpty}>
      <div className="flex flex-col items-center justify-center">
        <h1>Welcome!</h1>
        <p>How can I help you today?</p>

        <div className="grid grid-cols-2 gap-2">
          <ThreadPrimitive.Suggestions>
            {() => <SuggestionItem />}
          </ThreadPrimitive.Suggestions>
        </div>
      </div>
    </AuiIf>
  );
};

const SuggestionItem = () => {
  return (
    <SuggestionPrimitive.Trigger send asChild>
      <button className="rounded-lg border p-3 hover:bg-muted">
        <div className="font-medium">
          <SuggestionPrimitive.Title />
        </div>
        <div className="text-muted-foreground text-sm">
          <SuggestionPrimitive.Description />
        </div>
      </button>
    </SuggestionPrimitive.Trigger>
  );
};

Dismissal

Suggestions dismiss automatically once the user sends a message because thread.isEmpty becomes false. No extra state management is needed. If you want to dismiss suggestions without sending (for example, after a user clicks away), manage a local boolean and combine it with the AuiIf condition or a plain conditional render.

Suggestion Primitives

The primitives available for rendering suggestions are ThreadPrimitive.Suggestions, ThreadPrimitive.SuggestionByIndex, SuggestionPrimitive.Title, SuggestionPrimitive.Description, and SuggestionPrimitive.Trigger. ThreadPrimitive.SuggestionByIndex is useful when you need layout control over a specific suggestion slot rather than iterating all of them. For the full prop reference and usage patterns, see the Suggestion primitive docs.

Dynamic Suggestions

You can dynamically change suggestions based on your application state:

import { useMemo } from "react";

function MyRuntimeProvider({ children }: { children: React.ReactNode }) {
  const runtime = useChatRuntime();
  const user = useUser(); // Your user hook

  const suggestions = useMemo(() => {
    if (user.isPremium) {
      return [
        "Analyze my business data",
        "Generate a detailed report",
        "Create a custom workflow",
      ];
    }
    return [
      "What can you do?",
      "Tell me a joke",
      "Help me get started",
    ];
  }, [user.isPremium]);

  const aui = useAui({
    tools: Tools({ toolkit: myToolkit }),
    suggestions: Suggestions(suggestions),
  });

  return (
    <AssistantRuntimeProvider aui={aui} runtime={runtime}>
      {children}
    </AssistantRuntimeProvider>
  );
}

Best Practices

  1. Keep suggestions concise: Use clear, actionable prompts that users can understand at a glance
  2. Show capabilities: Use suggestions to highlight your assistant's key features
  3. Provide variety: Offer suggestions across different use cases
  4. Use the object format for complex suggestions: When you need separate title/description, use the object format
  5. Limit the number: 3-6 suggestions work best to avoid overwhelming users
  6. Make them actionable: Each suggestion should lead to a meaningful interaction

Switching from ThreadPrimitive.Suggestion

If your codebase uses the inline ThreadPrimitive.Suggestion component (which renders one suggestion at a time with hardcoded prompt / send props), you can move to the runtime-driven Suggestions() API for centralized configuration. The inline component is still supported, but the runtime-driven approach scales better when suggestions need to update dynamically.

Inline form

<ThreadPrimitive.Suggestion
  prompt="What's the weather?"
  send
/>

Runtime-driven form

  1. Configure suggestions in your runtime provider:
const aui = useAui({
  suggestions: Suggestions(["What's the weather?"]),
});
  1. Display suggestions using the primitives:
<ThreadPrimitive.Suggestions>
  {() => <SuggestionItem />}
</ThreadPrimitive.Suggestions>

The new API provides:

  • Centralized configuration: Define suggestions once in your runtime provider
  • Better separation of concerns: Configuration separate from presentation
  • Type safety: Full TypeScript support
  • Consistency: Follows the same pattern as the Tools API