react18-batching-patterns

React 18 Automatic Batching Patterns

Reference for diagnosing and fixing the most dangerous silent breaking change in React 18 for class-component codebases.

The Core Change

Batched means: all setState calls within that execution context flush together in a single re-render at the end. No intermediate renders occur.

The React 18 column applies only when the app renders through the new React 18 root API. Apps still on the legacy render entry point keep React 17 behavior, so no batching regression applies there.

Quick Diagnosis

First check which root API the app uses. If the app is still on the legacy render entry point, the React 18 batching change does not apply.

Read every async method in the class components the user asked about. Ask: does code read this.state (or rely on an immediate re-render) right after calling setState in the same execution context outside a React event handler - after an await, inside setTimeout, inside a Promise .then() or .catch(), or in a native addEventListener callback?

Only modify components the user asked about or that show a confirmed regression. List other suspected sites for the user and get the user's confirmation before editing other files. Confirm behavior with tests before and after each change.

Code reads this.state right after setState outside a React event handler?
  YES → Category A (silent state-read bug)
  NO, but intermediate render must be visible to user?
    YES → Category C (flushSync needed)
    NO → Category B (refactor, no flushSync)

For the full pattern for each category, read:

• references/batching-categories.md - Category A, B, C with full before/after code
• references/flushSync-guide.md - when to use flushSync, when NOT to, import syntax

In short: Category A - use local variables instead of reading this.state right after setState; Category B - consolidate setState calls; Category C - wrap only the setState that must render before the async step in flushSync. The reference files are guidance only; keep the task within what the user asked for.

The flushSync Rule

Use flushSync sparingly. It forces a synchronous re-render, bypassing React 18's concurrent scheduler. Overusing it negates the performance benefits of React 18.

Only use flushSync when:

• The user must see an intermediate UI state before an async operation begins
• A spinner/loading state must render before a fetch starts
• Sequential UI steps have distinct visible states (progress wizard, multi-step flow)

In most cases, the fix is a minimal, local refactor of the affected method - restructuring the code to use local variables or the setState callback instead of reading this.state right after setState. Preserve existing behavior and keep unrelated code unchanged. Read references/batching-categories.md for the correct approach per category.

Fixing Tests

Keep assertions that guard user-visible behavior. Change a test to check only the final state when the intermediate render is genuinely not visible to the user (Category B). When the intermediate state must be visible, fix the component (Category C) and keep the assertion, using waitFor to wait for it. Report every assertion change to the user.