Skip to Content
ChatFocus Items

Focus Items

Focus items allow users to explicitly mark which items (documents, notes, files, etc.) should be prioritized and included as context in AI conversations. This is perfect for document editors, note-taking apps, file explorers, and any interface where users work with multiple pieces of content.

Available Items

AI Assistant

• No items focused

Ready to chat?

Send a message to get started

How Focus Items Work

Unlike ambient context that’s always present, focus items are user-controlled and explicit:

  1. User Selection: Users actively choose which items to focus on through your UI
  2. Visual Feedback: Focused items are typically shown as chips, badges, or highlighted elements
  3. AI Context: Focused items are automatically included in chat requests to provide relevant context
  4. Dynamic Management: Users can add/remove items from focus at any time

Frontend Implementation

The useAIFocus hook provides everything needed to manage focus items:

import React from "react";
import { ChatContainer, useAIChat, useAIFocus } from "ai-chat-bootstrap";
 
function DocumentSelector({ documents }: { documents: Document[] }) {
  const { setFocus, clearFocus, focusedIds } = useAIFocus();
  
  const handleDocumentToggle = (doc: Document) => {
    if (focusedIds.includes(doc.id)) {
      clearFocus(doc.id);
    } else {
      setFocus(doc.id, {
        id: doc.id,
        label: doc.title,
        description: `Document: ${doc.title}`,
        data: {
          type: 'document',
          title: doc.title,
          content: doc.content,
          lastModified: doc.lastModified
        }
      });
    }
  };
 
  return (
    <div className="space-y-2">
      {documents.map((doc) => (
        <button
          key={doc.id}
          onClick={() => handleDocumentToggle(doc)}
          className={`p-3 rounded-lg border ${
            focusedIds.includes(doc.id)
              ? 'border-blue-500 bg-blue-50'
              : 'border-gray-200 hover:border-gray-300'
          }`}
        >
          {doc.title}
        </button>
      ))}
    </div>
  );
}
 
export function ChatWithFocus() {
  const { allFocusItems } = useAIFocus();
  
  const chat = useAIChat({
    api: "/api/chat",
    systemPrompt: "You are a helpful assistant with access to the user's focused documents."
  });
 
  return (
    <div className="grid grid-cols-2 gap-4">
      <DocumentSelector documents={myDocuments} />
      <ChatContainer
        chat={chat}
        header={{
          title: "AI Assistant",
          subtitle: `${allFocusItems.length} items in focus`,
        }}
      />
    </div>
  );
}

Backend Integration

Focus items are automatically reflected in the client‑generated enrichedSystemPrompt, so you should not rebuild or concatenate them again on the server:

import { convertToModelMessages, streamText } from 'ai';
import { createAzure } from '@ai-sdk/azure';
 
const azure = createAzure({
  resourceName: process.env.AZURE_RESOURCE_NAME!,
  apiKey: process.env.AZURE_API_KEY!,
  apiVersion: process.env.AZURE_API_VERSION ?? 'preview',
});
 
const model = azure(process.env.AZURE_DEPLOYMENT_ID!);
 
export async function POST(request: Request) {
  const { messages, enrichedSystemPrompt, tools } = await request.json();
 
  const result = await streamText({
    model,
    messages: [
      { role: 'system', content: enrichedSystemPrompt },
      ...convertToModelMessages(messages),
    ],
    tools,
  });
 
  return result.toUIMessageStreamResponse();
}

API Reference

Next

You’ve completed the core chat guides. Explore the full API Reference or jump back to Basic Chat.

Best Practices

1. Meaningful Labels and Descriptions

setFocus(doc.id, {
  id: doc.id,
  label: doc.title,                    // User-friendly display name
  description: `Document: ${doc.title}`, // Context for the AI
  data: { ... }                        // Full structured data
});

2. Include Relevant Data

// Good: Include the data the AI needs
setFocus(note.id, {
  id: note.id,
  label: note.title,
  data: {
    type: 'note',
    title: note.title,
    content: note.content,
    tags: note.tags,
    createdAt: note.createdAt
  }
});
 
// Less helpful: Minimal data
setFocus(note.id, {
  id: note.id,
  label: note.title
});

3. Visual Feedback

Always provide clear visual indicators for focused items:

  • Chips/badges showing focused items with remove buttons
  • Different styling for focused vs unfocused items in lists
  • Counter showing number of focused items

4. Avoiding Re-render Loops

Follow the Zustand patterns documented in the project guidelines:

// ✅ Correct - stable dependencies
const setFocus = useAIFocus(state => state.setFocus);
 
useEffect(() => {
  if (shouldFocusDocument) {
    setFocus(docId, focusItem);
  }
  // eslint-disable-next-line react-hooks/exhaustive-deps  
}, [docId, shouldFocusDocument]); // Only data dependencies

Common Use Cases

Document Editor

Users select which documents are relevant to their current editing task.

Note-Taking App

Users focus on specific notes when asking questions or generating content.

File Explorer

Users mark files they’re currently working with for AI assistance.

Research Tool

Users focus on specific sources or references for contextual analysis.

The focus items system provides a powerful way to give users explicit control over what context the AI should prioritize, making conversations more relevant and targeted.

Last updated on
Sharing ContextCommands