Chat - Suggestions

Display prompt suggestions in the empty state to help users get started with a conversation.

Suggestions are clickable prompts that appear when the message list is empty. Clicking a suggestion pre-fills the composer with the suggestion text, giving users a starting point for the conversation.

Basic usage

Pass an array of strings to the suggestions prop on ChatBox:

<ChatBox
  adapter={adapter}
  suggestions={[
    'What can you help me with?',
    'Summarize my latest report',
    'Write a follow-up email',
  ]}
/>

Suggestions are hidden once the first message appears in the conversation.

ChatSuggestion objects

For more control, pass ChatSuggestion objects instead of plain strings. This lets you set a display label that differs from the value pre-filled into the composer:

ChatSuggestion type

You can mix strings and objects in the same array. Strings are internally normalized to { value: string }.

Auto-submit

By default, clicking a suggestion only pre-fills the composer so the user can review or edit before sending. Set suggestionsAutoSubmit to automatically submit the message when a suggestion is clicked:

Disabling suggestions

Even when the suggestions prop is provided, you can disable the feature through the features prop:

<ChatBox
  adapter={adapter}
  suggestions={['What can you help me with?']}
  features={{ suggestions: false }}
/>

This is useful when you want to conditionally show suggestions based on application state without removing the prop itself.

Dynamic suggestions

Since suggestions is a standard React prop, you can compute it dynamically. The example below loads user-specific suggestions after sign-in and updates them once available:

function App() {
  const [suggestions, setSuggestions] = React.useState([
    'Get started',
    'View recent activity',
  ]);

  React.useEffect(() => {
    fetchUserSuggestions().then((personalized) => {
      setSuggestions(personalized);
    });
  }, []);

  return <ChatBox adapter={adapter} suggestions={suggestions} />;
}

Suggestions are only displayed in the empty state (when the message list has no messages), so dynamic updates only take effect before the first message is sent.

The ChatSuggestions component

When building a custom layout, use ChatSuggestions directly inside a ChatRoot provider:

import { ChatSuggestions } from '@mui/x-chat';
import { ChatRoot } from '@mui/x-chat/headless';

<ChatRoot adapter={adapter}>
  <ChatSuggestions suggestions={['Option A', 'Option B']} autoSubmit={false} />
</ChatRoot>;

The component renders a role="group" container with aria-label derived from the locale text system. Each suggestion renders as a <button> element.

Slots

See also

• Composer for how the pre-filled value flows into the text area.
• Adapter for how submitted suggestions reach your backend.

API

See the documentation below for a complete reference to all of the props and classes available to the components mentioned here.

• <ChatSuggestions />