# Context Attachments
URL: /concepts/additional-context/context-attachments

Context attachments enable you to display visual badges above the message input that automatically provide the AI with additional context. This helps the AI understand what the user is focused on and provide more relevant responses.

## How context attachments work

Context attachments appear as removable badges above the message input. When present, they automatically send contextual information to the AI, helping it:

* Focus on specific files, components, or pages the user is viewing
* Understand which part of your application the user is working on
* Provide more targeted and relevant responses
* Enable visual feedback showing what context is active

The feature also supports custom suggestions, allowing you to override Tambo's auto-generated suggestions with your own contextual suggestions.

## Basic Usage

The `useTamboContextAttachment` hook provides methods to manage context attachments:

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

function FileViewer({ file }) {
  const { addContextAttachment, removeContextAttachment } =
    useTamboContextAttachment();

  const handleSelectFile = () => {
    addContextAttachment({
      name: file.name,
      icon: <FileIcon />,
      metadata: {
        filePath: file.path,
        type: file.type,
      },
    });
  };

  return <button onClick={handleSelectFile}>Focus on {file.name}</button>;
}
```

## Context Attachment Structure

Each context attachment has the following structure:

```tsx
interface ContextAttachment {
  id: string; // Auto-generated unique identifier
  name: string; // Display name shown in the badge
  icon?: React.ReactNode; // Optional icon to display
  metadata?: Record<string, unknown>; // Additional data for the AI
}
```

## Hook API

The `useTamboContextAttachment` hook returns:

```tsx
const {
  attachments, // Array of active context attachments
  addContextAttachment, // Add a new context attachment
  removeContextAttachment, // Remove by ID
  clearContextAttachments, // Remove all attachments
  customSuggestions, // Current custom suggestions
  setCustomSuggestions, // Set custom suggestions
} = useTamboContextAttachment();
```

### Adding Context Attachments

Add a context attachment by calling `addContextAttachment` with a name and optional metadata:

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

// Simple text context
addContextAttachment({
  name: "Dashboard Page",
});

// With icon and metadata
addContextAttachment({
  name: "Button.tsx",
  icon: <FileIcon />,
  metadata: {
    filePath: "/src/components/Button.tsx",
    lineNumber: 42,
  },
});
```

The `id` field is automatically generated. If you add a context with the same `name` as an existing one, it will be ignored to prevent duplicates.

### Removing Context Attachments

Remove a specific context attachment by its ID:

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

removeContextAttachment(contextId);
```

Or clear all attachments at once:

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

clearContextAttachments();
```

### Displaying Active Attachments

Display the current attachments as badges:

```tsx
const { attachments, removeContextAttachment } = useTamboContextAttachment();

return (
  <div>
    {attachments.map((attachment) => (
      <div key={attachment.id}>
        {attachment.icon}
        <span>{attachment.name}</span>
        <button onClick={() => removeContextAttachment(attachment.id)}>
          ×
        </button>
      </div>
    ))}
  </div>
);
```

## Customizing Context Data

By default, context attachments send a standard structure to the AI. You can customize this by providing a `getContextHelperData` function to `TamboProvider`:

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

<TamboProvider
  apiKey="your-api-key"
  getContextHelperData={(context) => ({
    selectedFile: {
      name: context.name,
      path: context.metadata?.filePath,
      instruction: "Focus on this file when responding",
      // Add any custom fields
      language: context.metadata?.language,
      lastModified: context.metadata?.lastModified,
    },
  })}
>
  <App />
</TamboProvider>;
```

The function can be async to fetch additional data:

```tsx
<TamboProvider
  apiKey="your-api-key"
  getContextHelperData={async (context) => {
    const fileContent = await fetchFileContent(context.metadata?.filePath);
    return {
      selectedFile: {
        name: context.name,
        content: fileContent,
        instruction: "Use this file content to help the user",
      },
    };
  }}
>
  <App />
</TamboProvider>
```

## Custom Suggestions

Context attachments can be combined with custom suggestions to override Tambo's auto-generated suggestions:

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

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

  const handleSelectComponent = () => {
    addContextAttachment({
      name: component.name,
      metadata: { componentId: component.id },
    });

    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
setCustomSuggestions(null);
```

## Complete Example

Here's a complete example showing context attachments in a file browser:

```tsx
import { useTamboContextAttachment } from "@tambo-ai/react";
import { FileIcon, XIcon } from "lucide-react";

function FileBrowser({ files }) {
  const {
    attachments,
    addContextAttachment,
    removeContextAttachment,
    setCustomSuggestions,
  } = useTamboContextAttachment();

  const handleFileClick = (file) => {
    addContextAttachment({
      name: file.name,
      icon: <FileIcon className="w-4 h-4" />,
      metadata: {
        filePath: file.path,
        language: file.language,
      },
    });

    setCustomSuggestions([
      {
        id: "1",
        title: "Explain this file",
        detailedSuggestion: `Explain what ${file.name} does`,
        messageId: "",
      },
      {
        id: "2",
        title: "Suggest improvements",
        detailedSuggestion: `Suggest improvements to ${file.name}`,
        messageId: "",
      },
    ]);
  };

  return (
    <div>
      {/* Active Context Badges */}
      {attachments.length > 0 && (
        <div>
          {attachments.map((attachment) => (
            <div key={attachment.id}>
              {attachment.icon}
              <span>{attachment.name}</span>
              <button onClick={() => removeContextAttachment(attachment.id)}>
                <XIcon className="w-3 h-3" />
              </button>
            </div>
          ))}
        </div>
      )}

      {/* File List */}
      <div>
        {files.map((file) => (
          <button key={file.id} onClick={() => handleFileClick(file)}>
            <FileIcon />
            {file.name}
          </button>
        ))}
      </div>
    </div>
  );
}
```

## How It Works

When you add a context attachment:

1. The attachment is added to the `attachments` array and displayed as a badge
2. A context helper is automatically registered with `TamboContextHelpersProvider`
3. The context data is sent along with every message until the attachment is removed
4. When removed, the context helper is automatically unregistered

This automatic synchronization means you don't need to manually manage context helpers—just add and remove attachments as needed.

## Integration with Existing Context

Context attachments work alongside other context helpers:

* **Prebuilt helpers** like `currentTimeContextHelper` continue to work
* **Custom helpers** from `contextHelpers` prop are still sent
* **Manual context** via `additionalContext` is merged with attachment context
* All context sources are combined when sending messages

## Use Cases

Context attachments are particularly useful for:

* **Code editors**: Focus on specific files or functions
* **Dashboards**: Indicate which widget or section is active
* **Forms**: Show which field or step is being worked on
* **Multi-page apps**: Display the current page or route
* **Component libraries**: Highlight selected components