Use a 50ms default publication cadence for useChat in v8

[gr2m]

Background

#18525 fixed useChat throttling so a configured throttle limits the message snapshots published to React. Before that fix, throttling only delayed the subscription callback; unrelated React renders could still observe the latest chat.messages array for every stream chunk and bypass the configured cadence.

The fix intentionally preserved the current default: when throttle is omitted, message snapshots remain unthrottled. Applications therefore need to know that they should opt into throttling to avoid excessive React work during fast, high-frequency streams. This is particularly noticeable on slower devices or when rendering expensive content such as Markdown, tool calls, or context menus, as reported in #6166.

Changing the omitted default affects observable rendering behavior and is therefore appropriate for the next major release.

Goal (v8)

Use a 50ms publication cadence for useChat message snapshots when throttle is omitted, while preserving an explicit unthrottled opt-out:

throttle value	Behavior
omitted	Publish React message snapshots at a 50ms cadence
0	Publish every message snapshot without throttling
positive number	Publish at the configured cadence

Stream processing, tool handling, and callbacks should remain immediate. Only snapshots exposed to React should be paced.

The default cadence must include an immediate leading publication and a terminal flush so the final messages are visible on the same render where ready or error becomes observable, including aborts that transition back to ready.

Tasks

• Change the omitted useChat throttle default to 50ms in @ai-sdk/react.
• Preserve throttle: 0 as the explicit unthrottled opt-out.
• Add regression tests for omitted, zero, and custom throttle values.
• Verify an immediate leading publication and terminal message/status coherence for normal completion, errors, and aborts.
• Extend the deterministic browser reproduction from fix(react): throttle published useChat snapshots #18525 to cover both the new default and the explicit unthrottled opt-out.
• Update the useChat API documentation and examples to describe the new default and opt-out.
• Add a v7-to-v8 migration-guide entry explaining the rendering-semantics change.
• Add a major changeset for @ai-sdk/react.
• Decide whether equivalent UI hooks or framework integrations should adopt the same default for consistency.

Acceptance Criteria

• Omitting throttle caps normal React message publications at approximately 20 updates per second.
• throttle: 0 retains the existing per-update behavior.
• Explicit positive values continue to control the publication cadence.
• Stream consumption, callbacks, tool handling, and internal chat state are not delayed.
• Final messages and terminal status remain coherent in the same render.
• The behavior is covered by unit tests and a real browser reproduction.

Tradeoffs

The default protects applications that do not know they need to opt in today and provides a predictable upper bound on normal React rendering work. The cost is up to 50ms of additional visible text latency, fewer intermediate renders, and an explicit opt-out for applications that intentionally require per-chunk rendering.

References

• fix(react): throttle published useChat snapshots #18525 — fixes configured throttling and proposes this v8 follow-up
• Maximum update depth exceeded #6166 — maximum-update-depth reports under high-frequency streaming
• fix(react): throttle useChat messages snapshot to prevent maximum update depth error #17893 — original published-snapshot proposal
• feat(chat): throttle chat UI updates by default cloudflare/agents#2058 — practical use of a conservative UI cadence

[ai-sdk-factory]

Identify issue type

Identified as Feature
Confidence: High

Rationale

This requests a deliberate behavior change and API-default enhancement for the next major release, not a failure of the currently documented default behavior.

Evidence

• The issue proposes changing the omitted useChat throttle default from unthrottled updates to a 50ms publication cadence in v8.
• It adds a new explicit behavior contract where throttle: 0 opts out of throttling.
• The requested change is framed as a major-release rendering-semantics enhancement, while the prior concrete throttling bug was fixed separately in fix(react): throttle published useChat snapshots #18525.

[ai-sdk-factory]

Feature Analysis

Feature is not available.

Feature Description

• When @ai-sdk/react useChat omits throttle, publish React message snapshots with an immediate leading update and an approximately 50ms cadence, preserve throttle: 0 as unthrottled and positive values as custom cadences, and flush final messages with ready or error for completion, errors, and aborts without delaying stream processing, tools, or callbacks.
• Current main computes throttleWaitMs as throttle ?? experimental_throttle, and ReactChatState only wraps the publication callback when that value is truthy; consequently omitted throttle and throttle: 0 are both unthrottled, while positive values are throttled.
• The useChat reference explicitly documents undefined as disabling throttling, the browser reproduction passes throttle: 50 explicitly, and existing focused tests cover configured throttling and terminal coherence but not the proposed omitted default or explicit zero opt-out.

AI SDK Fit

• The feature fits the existing stable throttle option and the published-snapshot architecture introduced for configured useChat throttling, improving React rendering performance without altering chat stream semantics or provider behavior.
• Changing a stable option's omitted behavior is observably breaking but aligns with the repository's policy of allowing justified behavioral changes in a major release.
• The omitted, zero, and positive modes share one user goal, public option, behavioral contract, and acceptance criteria; tests, documentation, migration guidance, and the browser reproduction are coverage work rather than independently shippable features.

Implications / Considerations

• The core implementation appears limited to @ai-sdk/react, principally defaulting useChat's resolved throttle to 50ms after honoring throttle and the deprecated experimental_throttle alias; the existing truthy registration check already makes zero unthrottled.
• The existing throttleit dependency provides immediate leading execution and a trailing invocation, while useChat's status subscription already publishes the latest messages before ready or error; regression tests must ensure these guarantees remain correct together and that delayed callbacks after unsubscription or chat replacement are harmless.
• Unit tests should separately cover omitted, zero, custom positive, and deprecated-alias values; publication-rate and unrelated-render behavior; immediate leading publication; completion, error, and abort terminal coherence; and confirmation that onData, onToolCall, onError, onFinish, stream consumption, and internal chat state remain immediate.
• The deterministic ai-e2e-next browser reproduction should expose both omitted-default and throttle: 0 modes, verify the default stays near 20 normal snapshot updates per second, verify zero observes per-update behavior, and confirm the full final message is visible when terminal status renders.
• No provider integration, provider or UI-message protocol specification, @ai-sdk/provider interface, or provider-utils change is required because pacing occurs only in the React subscription layer after AbstractChat processes stream chunks.
• No public API in the ai package needs to be added or changed; UseChatOptions already exposes throttle?: number, so the change is source- and type-compatible but behaviorally breaking for applications that omitted it and intentionally relied on per-chunk rendering.
• The direct UI impact is limited to @ai-sdk/react useChat: visible text may lag by up to roughly 50ms and intermediate snapshots may be skipped, while throttle: 0 restores current behavior.
• React useCompletion also has an optional throttle with an unthrottled default, while Vue, Svelte, and Angular chat state implementations do not expose the same React snapshot mechanism; adopting equivalent defaults would require an explicit consistency decision but is not necessary to deliver or split this useChat request.
• Documentation should update the useChat reference, Chatbot guide, performance troubleshooting guidance, and relevant examples; a new v7-to-v8 migration-guide entry and major @ai-sdk/react release metadata should explain the changed default and throttle: 0 opt-out.
• The change introduces no provider credential, transport, network, or data-retention implications; the main risks are rendering latency, applications depending on every intermediate snapshot, timer behavior under background-tab throttling, and React scheduling variance around the approximate 20-updates-per-second target.

Relevant Documentation

• useChat
• Chatbot
• React error "Maximum update depth exceeded"
• Markdown Chatbot with Memoization
• Versioning

[ai-sdk-factory]

Feature implementation

Created feature implementation and opened PR: #18554

Summary

Updated @ai-sdk/react useChat to default omitted throttle values to 50ms while preserving throttle: 0 as unthrottled and positive custom cadences; added a major changeset.

Testing

Added runtime coverage for omitted, zero, custom, and deprecated throttle settings, immediate callbacks, leading publication, and completion, error, and abort coherence, plus compile-time option tests.

End-to-end Validation

• Extended and built the Next.js browser reproduction for default and unthrottled modes.
• Playwright confirmed 15 default-cadence snapshots versus 503 unthrottled snapshots, with all 1,000 characters visible at ready.

Documentation

Updated the useChat reference, chatbot guide, rendering troubleshooting guidance, and migration index, and added an AI SDK 7-to-8 migration entry describing the new default and throttle: 0 opt-out.