View source for Principle:Langchain ai Langgraph UI Component Management

{{PageInfo|type=Principle|title=Langchain_ai_Langgraph_UI_Component_Management}}
{| class="wikitable"
|-
! Attribute !! Value
|-
| '''Type''' || Principle
|-
| '''Knowledge Sources''' || [https://github.com/langchain-ai/langgraph LangGraph]
|-
| '''Domains''' || UI, Graph, Streaming
|-
| '''Last Updated''' || [[last_updated::2026-02-11 15:00 GMT]]
|}

== Overview ==

UI component management in LangGraph enables graph nodes to push, update, merge, and delete UI component messages during execution, providing a real-time bridge between backend graph processing and frontend rendering.

=== Description ===

LangGraph provides a dedicated UI message system that allows graph nodes to communicate UI state changes to connected clients. The system operates through two complementary APIs:

'''Imperative API''' -- The `push_ui_message` and `delete_ui_message` functions are called directly from within graph nodes. When invoked, they immediately stream UI events to connected clients via the stream writer and simultaneously update the graph state channel. This enables real-time UI updates as the graph executes.

'''Reducer-based API''' -- The `ui_message_reducer` function is designed to be used as an `Annotated` reducer on a state key (typically `"ui"`). It handles the merging of incoming UI messages with existing ones, supporting add, update, merge, and remove operations. The reducer ensures idempotent state management by matching messages by their unique `id` field.

The system defines two message types: `UIMessage` (representing a component to render, with a name, props dictionary, and metadata) and `RemoveUIMessage` (representing a deletion request). The `push_ui_message` function supports a `merge` mode where subsequent pushes with the same `id` merge their props into the existing message rather than replacing it entirely, enabling incremental UI updates such as progress bars or streaming text content.

Each UI message carries a unique identifier, allowing the frontend to track component lifecycle from creation through updates to deletion. The `metadata` field supports additional context such as `run_id`, tags, and message associations.

=== Usage ===

Use the UI message system when building interactive applications where the graph needs to communicate visual state to a frontend. Common use cases include displaying progress indicators during long-running operations, showing intermediate results as chat bubbles, rendering custom visualization components, and managing loading states. Define the `ui` state key with the `ui_message_reducer` and call `push_ui_message` from nodes to stream components to the client.

== Theoretical Basis ==

The UI component management system implements a '''command pattern''' for UI state mutations. Each `UIMessage` or `RemoveUIMessage` acts as a command object that describes a state change, and the reducer applies these commands sequentially to produce the final UI state. This makes UI state changes auditable, replayable, and compatible with LangGraph's checkpoint system.

The dual API design (imperative for streaming, reducer for state) follows the '''CQRS (Command Query Responsibility Segregation)''' pattern: the imperative API optimizes for real-time write operations (pushing events to clients), while the reducer-based API optimizes for consistent state reconstruction (merging and replaying UI state from checkpoints).

The `merge` mode for incremental property updates implements an '''event sourcing''' approach where partial updates are accumulated over time, enabling efficient streaming of large or evolving UI components without retransmitting the full component state on every change.

== Related Pages ==

* [[implemented_by::Implementation:Langchain_ai_Langgraph_UI_Messages]]
* [[Langchain_ai_Langgraph_Graph_Execution]]
* [[Langchain_ai_Langgraph_Runtime_Context]]
* [[Langchain_ai_Langgraph_State_Schema_Definition]]

[[Category:Principles]]