Store and render complete chat history
Conversation interfaces
AI Tools · Type Alias
UIMessage
UIMessage is the AI SDK’s complete, UI-facing representation of a message and its application state. It carries identity, role, optional metadata, and typed parts for rendering text, data, and tool interactions.
How it works
UIMessage models the complete message state used by an application interface. It includes the message identity and role, optional application metadata, and typed parts for rendering text, data, and tool interactions.
Syntax
interface UIMessage<
METADATA = unknown,
DATA_PARTS extends UIDataTypes = UIDataTypes,
TOOLS extends UITools = UITools,
> {
id: string;
role: 'system' | 'user' | 'assistant';
metadata?: METADATA;
parts: Array<UIMessagePart<DATA_PARTS, TOOLS>>;
}Parameters
| Name | Type | Description |
|---|---|---|
METADATA | unknown | Custom type for additional message information; defaults to unknown. |
DATA_PARTS | UIDataTypes | Custom data-part types; constrained by UIDataTypes and defaulting to UIDataTypes. |
TOOLS | UITools | Tool definitions for typed tool interactions; constrained by UITools and defaulting to UITools. |
Returns
A UIMessage object with id, role, optional metadata, and typed parts.
Key points
- Use UIMessage as the canonical client-side representation of an application's conversation state.
- It captures more than conversational text: the history can include metadata, custom data, and other UI context.
- The type is designed for interface rendering and client-side behavior rather than only model input.
- Supply generics when the application needs compile-time types for metadata, custom data parts, or tools.
- Every message includes an id field that identifies it uniquely.
- The role field distinguishes system, user, and assistant messages.
Example: Create a UIMessage
import type { UIMessage } from 'ai';
const message: UIMessage = {
id: 'msg-1',
role: 'user',
parts: [{ type: 'text', text: 'Hello!' }],
};
console.log(message.parts);Creates a UIMessage with the required identifier, role, and renderable parts.
When to use it
Attach custom metadata and structured data parts
Typed application state
Represent typed tool calls and their results
Generative UI
Provide messages to AI SDK UI components
Client-side chat state
Interview questions
QHow does UIMessage differ from ModelMessage?
UIMessage represents the full application-facing message, including metadata, data parts, and contextual information needed by the UI. ModelMessage is instead the model-facing representation.
Follow-up: How would you adapt UIMessage before sending it to a model? Use convertToModelMessages to transform the UIMessage array into the ModelMessage format.
QWhat can be customized through UIMessage generics?
The type accepts METADATA, DATA_PARTS, and TOOLS generic parameters. These let an application type custom metadata, structured data parts, and tool interactions.
Follow-up: What should the defaults be when customization is unnecessary? The documented defaults are unknown for metadata and the standard UIDataTypes and UITools types for the other parameters.
QWhat are the main fields of UIMessage?
A UIMessage has an id string, a role restricted to system, user, or assistant, optional metadata, and a parts array of UIMessagePart values. Parts are intended for rendering the message in the interface.
Follow-up: Where should tool-specific rendering logic look? It should inspect the typed parts, including tool parts whose names identify the tool.
Related
ModelMessageUIMessagePartUIDataTypesUIToolsInferUIToolsconvertToModelMessages