OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add patternsdev/skills --skill ai-ui-patterns
Teaches design patterns for building AI-powered React interfaces. Use when creating chatbots, intelligent assistants, streaming UIs, or any AI-driven user experience in React.
npx skills add patternsdev/skills --skill ai-ui-patterns
Building AI-powered interfaces – from chatbots to intelligent assistants – requires careful integration of backend AI services with reactive UI components. In this chapter, we explore design patterns in React for such interfaces, focusing on two implementations: a plain React app (using Vite) and a Next.js app. We'll use OpenAI's API (via the Vercel AI SDK) as our AI engine, and TailwindCSS for styling. Key topics include prompt management, streaming responses, input debouncing, error handling, and how these patterns differ between Vite and Next.js. We also highlight reusable component patterns and Vercel's AI UI components (AI Elements) for building polished chat UIs.
useChat hook for managing conversation state and streaming responsesstream: true) for responsive real-time output in chat interfacesNote: While this article uses OpenAI as an example, the Vercel AI SDK supports multiple model providers including Gemini, OpenAI, and Anthropic. You can easily swap between providers through the SDK's unified interface – we're just choosing one option for demonstration purposes.
AI-driven user interfaces (UIs) have become popular with the rise of LLMs like ChatGPT. Unlike traditional UIs, AI interfaces often involve conversational interactions, dynamic content streaming, and asynchronous backend calls. This introduces unique challenges and patterns for React developers. A typical AI chat interface consists of a frontend (for user input and displaying responses) and a backend (to call the AI model). The backend is essential to keep API keys and heavy processing off the client for security and performance. Tools like Vercel's AI SDK make it easier to connect to providers (OpenAI, HuggingFace, etc.) and stream responses in real-time. We'll explore how to set up both a Next.js app and a Vite (React) app to handle these concerns, and discuss best practices that apply to both.
Key patterns covered:
By the end, you'll be equipped to build a responsive, robust AI-powered UI in React, whether you prefer Next.js or a Vite toolchain.
Before diving into code, ensure you have the necessary packages and configurations:
React & Vite: Initialize a Vite + React project (e.g. npm create vite@latest my-ai-app -- --template react). For Next.js, you can use npx create-next-app or the Next 13 App Router templates. Both will work – we'll highlight differences as we go.
TailwindCSS: Set up Tailwind in your project for quick styling.
OpenAI API & Vercel AI SDK: Install OpenAI's library or the Vercel AI SDK. We will use Vercel's AI SDK (npm i ai) which provides helpful React hooks (useChat, useCompletion) and server utilities. This SDK is framework-agnostic, working with Next.js, vanilla React, Svelte, and more. It simplifies streaming and state management, and is free/open-source.
API Keys: Get your OpenAI API key from the OpenAI dashboard and store it safely. In Next.js, put it in .env.local (e.g. OPENAI_API_KEY=sk-...) and never commit it. In a Vite app, do not expose the key in client code – instead, use a backend proxy or environment variable on the server.
Next.js Implementation: Next.js allows us to create route handlers as serverless functions. We can define an API route that the React front-end will call for AI responses:
In this handler, we receive a JSON body containing an array of messages (chat history). We call OpenAI's chat completion with stream: true to get a streaming response. We then wrap the response in a StreamingTextResponse provided by the AI SDK to pipe it back to the client in chunks. The Next.js API route keeps our API key on the server and streams data efficiently.
Vite (React) Implementation: In a Vite app, there's no built-in server, so we need to create our own backend for the OpenAI calls. This can be a simple Node/Express server:
During development, you can configure the Vite dev server to proxy /api calls to this backend (e.g. in vite.config.js, set server.proxy['/api'] = 'http://localhost:6000'). The key is that the React app calls a relative /api/chat endpoint, which the proxy/hosting will route to your server code. This keeps the OpenAI key hidden.
Enabling Streaming in Node: The above Express example returns the full response after completion (stream: false for simplicity). To stream in Node, you can use OpenAI's HTTP stream: set stream: true and handle the response as a stream of data. This involves reading the response.data stream and flushing chunks to the client with res.write(). If you choose to stick with full responses (no streaming), the UI patterns still largely apply – but streaming greatly improves UX.
At the heart of any AI interface is prompt management – assembling user input (and context) into a prompt or message sequence for the AI model. In a chat scenario, we maintain a list of messages, each with a role and content. OpenAI's Chat API expects messages in the format { role: 'user' | 'assistant' | 'system', content: string }. We typically start with a system message (to set the assistant's behavior or context), followed by alternating user and assistant messages as the conversation progresses.
State management in React: We can store the conversation in component state. Using the Vercel SDK's React hook:
The useChat hook handles a lot for us: it manages the messages state (an array of message objects), an input state for the current text input, and provides handleInputChange and handleSubmit helpers. By default, useChat() will POST to /api/chat when you submit.
Manual state handling: If you aren't using useChat, you can manage state with useState or context. On form submit, call your API and then update the messages array by appending the user query and the assistant's response.
System prompts and context: A common pattern is including an initial system message describing the assistant's role or knowledge base. For example, if building a docs helper, system content might be "You are a documentation assistant. Answer with examples from the docs."
Single-turn vs multi-turn: If your interface is a single question answering (no conversation memory), you could use the useCompletion hook from the Vercel SDK instead. For chatbots and multi-turn dialogs, useChat is the go-to pattern, since it retains and sends the message history on each request.
One hallmark of modern AI UI is streaming output: as the AI generates tokens, the user sees the reply appearing in real-time. This is crucial for better UX because model-generated answers can be lengthy or slow. Instead of waiting many seconds in silence, streaming lets us display partial results immediately.
How streaming works: When we enabled stream: true on the OpenAI API, the response is sent as a sequence of chunks (data events) rather than one JSON blob. The Vercel AI SDK simplifies consumption of these chunks. On the server, we turned the response into a text stream (StreamingTextResponse). On the client side, the useChat hook handles reading this stream and updating the messages state incrementally as new text arrives.
If you implement streaming manually in React (without the SDK), you would do something like:
Auto-scrolling: One UX detail when streaming is ensuring the latest message is visible. A pattern to handle this is auto-scrolling the message container on update with a useEffect watching the messages array length.
Partial rendering and completion: Show a visual indicator during streaming – for example, a blinking cursor or "AI is typing…" message. Once the stream finishes, finalize the message display.
For chat interactions, you usually send the query when the user submits the form. In some AI applications, however, you might want to react to input continuously – for example, autocomplete suggestions or real-time validation by AI. In such cases, debouncing is important.
Why debounce? Calling the OpenAI API on every keystroke would be extremely inefficient and costly. Debouncing delays the API call until the user has stopped typing for a short period.
For a simple chatbot with explicit "send" action, debouncing is usually not needed – you send when the user hits Enter. However, it's still useful to disable the input or prevent multiple submissions while an AI response is in progress.
Robust error handling is vital in AI applications:
Try/Catch around API calls: On the server, wrap the OpenAI call in try/catch. Return a proper error response if something fails.
Client-side error state: Handle cases where the response indicates an error.
User feedback: Always inform the user when something goes wrong. Display the error inline in the chat – e.g., as a special "system" message saying "Sorry, something went wrong. Please try again."
Retry mechanism: Consider allowing the user to retry with a "Try again" button.
Validation errors: Validate on the client before calling the API. Disable send on empty input, or truncate inputs that exceed some length.
Chat message components: Create a ChatMessage component that renders a single message bubble. Based on role, style it differently:
Input component:
Composition:
This separation of concerns makes it easy to test and swap UI parts. The logic (useChat) is decoupled from the display components.
Vercel's AI Elements library offers a set of ready-made React components specifically designed for AI chat interfaces:
Backend API Route: Whether using Next.js route handlers or a separate Express server, create an endpoint that receives messages, calls the AI model, and streams the response back.
State Management: Use the Vercel AI SDK's useChat hook (or roll your own with useState) to manage the conversation state.
Streaming: Enable streaming on both server and client for responsive UX.
Debouncing & Rate Limiting: For features like autocomplete, debounce API calls. For chat, disable input during response streaming.
Error Handling: Wrap API calls in try/catch, provide user feedback on errors, and consider retry mechanisms.
Reusable Components: Build presentational components (ChatMessage, InputBox) that are decoupled from data-fetching logic. Consider using AI Elements for production-ready components.
Styling: Use TailwindCSS (or your preferred styling solution) to create a clean, responsive chat interface.
| Aspect | Next.js | Vite + Node Backend |
|---|---|---|
| API Routes | Built-in (pages/api/ or app/api/) | Separate Express/Node server required |
| Streaming | Native support with Edge Runtime | Manual implementation with res.write() |
| Deployment | Vercel (optimized) or self-host | Deploy frontend (static) + backend separately |
| Complexity | Lower (all-in-one) | Higher (two codebases) |
| Flexibility | Framework conventions | Full control |
For most AI chat applications, Next.js provides a simpler developer experience with its integrated API routes and streaming support. However, if you have an existing Vite/React app or prefer more control, the patterns described here work well with a separate backend.
// backend/server.js (Node/Express for Vite app)
import express from 'express';
import { Configuration, OpenAIApi } from 'openai';
const app = express();
app.use(express.json());
const config = new Configuration({ apiKey: process.env.OPENAI_API_KEY });
const openai = new OpenAIApi(config);
app.post('/api/chat', async (req, res) => {
try {
const { messages = [] } = req.body;
const systemMsg = { role: 'system', content: 'You are a helpful assistant.' };
const inputMessages = [systemMsg, ...messages];
const response = await openai.createChatCompletion({
model: 'gpt-3.5-turbo',
stream: false,
messages: inputMessages
});
const content = response.data.choices[0].message?.content;
res.json({ content });
} catch (err) {
console.error(err);
res.status(500).json({ error: 'Internal Server Error' });
}
});
app.listen(6000, () => console.log('API server listening on http://localhost:6000'));import { useChat } from 'ai/react';
function ChatInterface() {
const { messages, input, handleInputChange, handleSubmit } = useChat();
// ...
}const res = await fetch('/api/chat', { method: 'POST', body: JSON.stringify({ messages }) });
const reader = res.body.getReader();
const decoder = new TextDecoder();
let partial = "";
while(true) {
const { value, done } = await reader.read();
if (done) break;
partial += decoder.decode(value);
setAssistantMessage(partial);
}const [draft, setDraft] = useState("");
useEffect(() => {
if (!draft) return;
const timeout = setTimeout(() => {
getSuggestion(draft);
}, 500);
return () => clearTimeout(timeout);
}, [draft]);try {
await sendMessage({ text: input });
} catch (error) {
console.error("Failed to send message:", error);
}function ChatMessage({ role, content }) {
const isUser = role === 'user';
return (
<div className={`flex ${isUser ? 'justify-end' : 'justify-start'} mb-2`}>
<div className={`max-w-xl px-4 py-2 rounded-lg ${
isUser ? 'bg-blue-500 text-white' : 'bg-gray-200 text-gray-900'
}`}>
{content}
</div>
</div>
);
}function InputBox({ value, onChange, onSubmit, disabled }) {
return (
<form onSubmit={onSubmit} className="flex gap-2">
<input
type="text"
value={value}
onChange={onChange}
disabled={disabled}
className="flex-1 border rounded px-3 py-2"
placeholder="Type your message..."
/>
<button type="submit" disabled={disabled} className="bg-blue-500 text-white px-4 py-2 rounded">
Send
</button>
</form>
);
}function ChatInterface() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
return (
<div className="flex flex-col h-screen max-w-2xl mx-auto p-4">
<div className="flex-1 overflow-y-auto">
{messages.map((msg, i) => (
<ChatMessage key={i} role={msg.role} content={msg.content} />
))}
</div>
<InputBox
value={input}
onChange={handleInputChange}
onSubmit={handleSubmit}
disabled={isLoading}
/>
</div>
);
}import { Conversation, Prompt, TypingIndicator } from '@vercel/ai-elements';
function ChatApp() {
const { messages, input, handleInputChange, handleSubmit, isLoading } = useChat();
return (
<div className="h-screen flex flex-col">
<Conversation messages={messages} />
{isLoading && <TypingIndicator />}
<Prompt
value={input}
onChange={handleInputChange}
onSubmit={handleSubmit}
/>
</div>
);
}