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:

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

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

      {/* Display suggestions */}
      <div className="grid grid-cols-2 gap-2">
        <ThreadPrimitive.Suggestions
          components={{
            Suggestion: SuggestionItem,
          }}
        />
      </div>
    </div>
  );
};

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>
  );
};

Suggestion Primitives

ThreadPrimitive.Suggestions

Renders all suggestions from the suggestions scope.

<ThreadPrimitive.Suggestions
  components={{
    Suggestion: CustomSuggestionComponent,
  }}
/>

SuggestionPrimitive.Title

Displays the suggestion's title (the first part when using object format, or the full text when using strings).

<SuggestionPrimitive.Title />

SuggestionPrimitive.Description

Displays the suggestion's description/label (only shown when using object format).

<SuggestionPrimitive.Description />

SuggestionPrimitive.Trigger

A button that triggers the suggestion action when clicked.

<SuggestionPrimitive.Trigger
  send={true}
  clearComposer={true}
  asChild
>
  <button>Click me</button>
</SuggestionPrimitive.Trigger>

Props:

  • send (boolean): When true, automatically sends the message. When false, only populates the composer.
  • clearComposer (boolean, default: true): When send is false, determines if the composer is cleared before adding the suggestion (true) or if the suggestion is appended (false).
  • asChild (boolean): Merge props with child element instead of rendering a button.

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>
  );
}

Context-Aware Suggestions

Suggestions can be tailored to different contexts or user intents:

const suggestions = [
  {
    title: "Code Review",
    label: "Get feedback on your code",
    prompt: "Can you review this code for me?",
  },
  {
    title: "Debug Help",
    label: "Find and fix issues",
    prompt: "Help me debug this error",
  },
  {
    title: "Best Practices",
    label: "Learn recommended patterns",
    prompt: "What are the best practices for this?",
  },
];

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

Migration from Legacy API

If you're using the deprecated ThreadPrimitive.Suggestion component, migrate to the new API:

Before (Deprecated)

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

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