# Suggestions
URL: /concepts/suggestions

Tambo automatically analyzes user interactions and generates contextual suggestions after each assistant message. You can also override these with custom suggestions using the `useTamboContextAttachment` hook.

## Using Suggestions

### The useTamboSuggestions Hook

The main way to interact with suggestions is through the `useTamboSuggestions` hook:

```tsx title="thread-with-suggestions.tsx"
import { useTamboSuggestions } from "@tambo-ai/react";

function ThreadWithSuggestions() {
  const {
    suggestions, // Array of current suggestions
    isLoading, // Whether suggestions are being generated or loading
    isAccepting, // Whether a suggestion is being applied
    error, // Current error message, if any
    accept, // Function to apply a suggestion
  } = useTamboSuggestions({
    maxSuggestions: 3, // Optional: Number of suggestions to generate (1-10)
  });

  if (isLoading) return <LoadingSpinner />;
  if (error) return <ErrorMessage>{error}</ErrorMessage>;

  return (
    <div>
      {suggestions.map((suggestion) => (
        <button
          key={suggestion.id}
          onClick={() => accept(suggestion)}
          disabled={isAccepting}
          title={suggestion.title}
        >
          {suggestion.title}
        </button>
      ))}
    </div>
  );
}
```

### Hook Configuration

The `useTamboSuggestions` hook accepts an optional configuration object:

```tsx title="thread-with-suggestions.tsx"
interface UseTamboSuggestionsOptions {
  /** Maximum number of suggestions to generate (1-10, default 3) */
  maxSuggestions?: number;
}
```

### When Suggestions Appear

Suggestions are automatically generated after each assistant (tambo) message in the thread. The hook manages:

* Loading states while generating suggestions
* Error handling for failed generations
* Automatic cleanup when messages change

### Accepting Suggestions

The `accept` function provides two modes:

```tsx title="thread-with-suggestions.tsx"
// Just set the suggestion text in the input
accept(suggestion);

// Set text and automatically submit
accept(suggestion, true);
```

## Suggestion Types

### Basic Suggestion Structure

```tsx title="thread-with-suggestions.tsx"
interface Suggestion {
  /** Unique identifier for the suggestion */
  id: string;
  /** Short title or summary of the suggestion */
  title: string;
  /** Detailed explanation of the suggestion */
  detailedSuggestion: string;
  /** ID of the message this suggestion is for */
  messageId: string;
  /** Additional metadata for the suggestion */
  metadata?: Record<string, string>;
}
```

### State Management Types

The hook uses additional types for state management:

```tsx title="thread-with-suggestions.tsx"
type SuggestionState = {
  /** List of current suggestions */
  items: Suggestion[];
  /** Whether suggestions are currently being loaded */
  loading: boolean;
  /** Current error message, if any */
  error: string | null;
};
```

## Error Handling

The hook provides built-in error handling for common scenarios:

```tsx title="thread-with-suggestions.tsx"
const ERROR_MESSAGES = {
  GENERATION: "Unable to generate suggestions right now",
  EMPTY: "No suggestions available for this message",
  ACCEPT: "Unable to apply suggestion, please try again",
  API_ERROR: "Failed to communicate with tambo",
};
```

## Integration Example

Here's a complete example showing how to integrate suggestions with a message thread:

```tsx title="thread-with-suggestions.tsx"
import { useTamboThread, useTamboSuggestions } from "@tambo-ai/react";

function MessageThread() {
  const { thread } = useTamboThread();
  const { suggestions, isLoading, isAccepting, error, accept } =
    useTamboSuggestions();

  // Get the latest message
  const latestMessage = thread.messages[thread.messages.length - 1];
  const isLatestFromHydra = latestMessage?.role === "assistant";

  return (
    <div>
      {/* Messages */}
      {thread.messages.map((message) => (
        <div key={message.id}>{message.content}</div>
      ))}

      {/* Suggestions (only shown after tambo messages) */}
      {isLatestFromHydra && (
        <div className="suggestions">
          {isLoading && <LoadingSpinner />}
          {error && <ErrorMessage>{error}</ErrorMessage>}
          {suggestions.map((suggestion) => (
            <button
              key={suggestion.id}
              onClick={() => accept(suggestion)}
              disabled={isAccepting}
            >
              {suggestion.title}
            </button>
          ))}
        </div>
      )}
    </div>
  );
}
```

<Callout type="info">
  Suggestions are automatically generated for each tambo message when the
  `useTamboSuggestions` hook is used. You don't need to manually trigger
  suggestion generation.
</Callout>

## Custom Suggestions

You can override auto-generated suggestions with your own custom suggestions using the `useTamboContextAttachment` hook:

```tsx
import { useTamboContextAttachment } from "@tambo-ai/react";

function ComponentSelector({ component }) {
  const { setCustomSuggestions } = useTamboContextAttachment();

  const handleSelectComponent = () => {
    setCustomSuggestions([
      {
        id: "1",
        title: "Edit this component",
        detailedSuggestion: `Modify the ${component.name} component`,
        messageId: "",
      },
      {
        id: "2",
        title: "Add a feature",
        detailedSuggestion: `Add a new feature to ${component.name}`,
        messageId: "",
      },
    ]);
  };

  return <button onClick={handleSelectComponent}>Select Component</button>;
}
```

To clear custom suggestions and return to auto-generated ones:

```tsx
const { setCustomSuggestions } = useTamboContextAttachment();

setCustomSuggestions(null);
```

Custom suggestions are particularly useful when combined with [context attachments](/concepts/additional-context/context-attachments) to provide focused, contextual actions based on what the user is currently viewing or working on.