Hooks Implementation

Relevant source files

This page details the internal implementation of React Hooks within the React reconciler, focusing primarily on the ReactFiberHooks.js file. It covers the dispatcher pattern that enables environment-specific hook behavior, distinguishes mount versus update paths, explains the integration of useActionState with forms, describes the server-side hook dispatchers in React Fizz (ReactFizzHooks.js), and elucidates the React DevTools debug hooks API.

Dispatcher Pattern

React employs a dispatcher pattern to dynamically switch hook implementations depending on the current rendering environment (mount, update, server, or debug). This pattern is managed via the global dispatcher reference stored at ReactSharedInternals.H packages/react/src/ReactHooks.js24-42

When a hook like useState or useEffect is called inside a component render, it delegates to the current dispatcher method, allowing React to adapt hook semantics based on whether it is mounting, updating, rendering on the server, or interacting with DevTools.

Dispatcher Implementations

Mount Dispatcher: Handles hook initialization during the first render (mounting).
Update Dispatcher: Handles processing of hooks during re-renders (updates).
Server Dispatcher: Used in React Fizz server rendering to implement hooks that support streaming server components.
Debug Dispatcher: Used by React DevTools to inspect hook state during component inspection.

Diagram: Hooks Dispatcher Pattern

Sources:

Hook Data Structure

Hooks are internally represented as linked list nodes attached to the fiber’s memoizedState. Each hook node tracks its current state and updates through the following structure:

memoizedState: The current state or value of the hook.
baseState and baseQueue: Used for maintaining correct state and update queue consistency especially under concurrent rendering.
queue: The update queue for hooks like useState or useReducer.
next: Reference to the next hook in the list.

The hooks form a singly linked list, with one node per hook call, corresponding to the hook call order in the component function packages/react-reconciler/src/ReactFiberHooks.js194-200 packages/react-reconciler/src/ReactInternalTypes.js149-151

During rendering, React maintains pointers currentHook (previous render’s hook) and workInProgressHook (currently processing hook) to traverse and manage the list of hooks packages/react-reconciler/src/ReactFiberHooks.js310-330

Sources:

Mount vs. Update Paths

React splits the lifecycle of hooks distinctly between mount (initial render) and update (re-render), allowing precise and optimized management of state and side effects. This is realized as separate dispatchers with specialized implementations.

Mount Path

During the initial render, the mount dispatcher is active. For each hook call:

A new Hook node is created using createWorkInProgressHook().
The hook initializes its memoized state, refs, effects, or other internal values based on provided initial arguments.
Effect hooks schedule their effect objects on the fiber’s effect list.

Diagram: Hooks Mount Path

Sources:

Update Path

During an update render, React switches to the update dispatcher, which:

Retrieves the existing Hook node from the previous fiber via updateWorkInProgressHook().
Processes pending updates from the hook’s update queue to compute the new state.
Compares previous and new dependency arrays for effects to determine whether effects should re-run or be skipped.

Diagram: Hooks Update Path

Sources:

State Update Queue

Hooks that maintain state (useState, useReducer) use a circular linked list of update objects recording:

The lane (priority) for scheduling and concurrency.
The action representing the change (state or reducer action).
An eager state computed during dispatch to optimize bailing out of updates.

This mechanism aligns with React’s concurrent mode rendering where multiple updates with different priorities may be pending simultaneously packages/react-reconciler/src/ReactFiberHooks.js174-180 packages/react-reconciler/src/ReactFiberHooks.js1060-1066

Sources:

`useActionState` and Form Integration

useActionState is a dedicated hook facilitating integration with React’s server and client form actions, previously known as useFormState.

Client-Side Implementation in ReactFiberHooks.js

useActionState maintains a state linked to a form action.
It initializes with the provided initial state and returns a dispatch function to run the associated action.
When dispatched, if the action returns a promise, it sets isPending state until resolved, then updates the state and requests a re-render.
The root fiber contains a formState object that manages the form-related state lifecycle including hydration packages/react-reconciler/src/ReactFiberHooks.js1700-1790 packages/react-reconciler/src/ReactFiberRoot.js110

Server-Side Implementation in ReactFizzHooks.js

The hook reads the form state snapshot from the current Request object’s formState.
It matches the hook index with the corresponding actionStateMatchingIndex in the server’s form state.
Returns the current form state for that action.
Dispatching on the server is a no-op as form actions run client-side or via the server action protocol.

Diagram: useActionState Lifecycle Flow on Client and Server

Sources:

Server-Side Hook Dispatchers (ReactFizzHooks)

The React Fizz server renderer uses a specialized hooks dispatcher in ReactFizzHooks.js optimized for streaming server components.

Key Characteristics

No Side Effects: Hooks like useEffect, useInsertionEffect, and useLayoutEffect are no-ops because no browser environment is involved packages/react-server/src/ReactFizzHooks.js300-310
State Hooks: useState and useReducer only establish initial state; updates are deferred and do not process on the server packages/react-server/src/ReactFizzHooks.js220-240
Deterministic IDs: useId generates consistent IDs for server/client hydration packages/react-server/src/ReactFizzHooks.js400-420
use: Supports suspension on thenables/promises for server components streaming packages/react-server/src/ReactFizzHooks.js430-490
useActionState: Reads from the server form state and provides a no-op dispatch packages/react-server/src/ReactFizzHooks.js500-550

Render Context Management

The server hooks maintain contextual variables such as:

currentlyRenderingComponent
currentlyRenderingTask
currentlyRenderingRequest
Hook linked lists (firstWorkInProgressHook and workInProgressHook)

before a server component render via the prepareToUseHooks function packages/react-server/src/ReactFizzHooks.js206-212

Sources:

Debug Tools API

React DevTools integrates via the react-debug-tools package utilizing a debug hooks dispatcher in ReactDebugHooks.js. This dispatcher wraps hook calls to collect detailed debug information.

Inspection Workflow

When DevTools requests inspection with inspectHooksOfFiber(fiber), it temporarily replaces the global hook dispatcher with the debug dispatcher.
The component is re-rendered under this debug dispatcher.
Each hook call is logged to a hookLog with debug info such as values, stack frames, and hook names packages/react-debug-tools/src/ReactDebugHooks.js40-140
The original dispatcher is restored after inspection.
DevTools renders the collected hook tree with states in its UI.

Diagram: DevTools Hooks Inspection Process

Sources:

Summary

React’s hooks implementation is built around a versatile dispatcher pattern that allows selection of environment-specific hook semantics—covering initial mounts, updates, server-side rendering, and debugging. Hooks themselves are linked lists attached to Fibers, with sophisticated update queue management for concurrent rendering.

The useActionState hook integrates closely with React’s form and server action functionality, handling client and server semantics distinctly. React Fizz leverages a streamlined server-side hooks dispatcher, disabling client-only side effects and supporting the Suspense-driven streaming model of React Server Components.

React DevTools employs a debug hooks dispatcher to introspect hooks state, facilitating powerful developer tooling and inspection features.

This architecture balances concurrency, streaming rendering, seamless server/client integration, and robust debugging.

References & Sources

Hooks Implementation

Relevant source files

Dispatcher Pattern

Dispatcher Implementations

Mount Dispatcher: Handles hook initialization during the first render (mounting).
Update Dispatcher: Handles processing of hooks during re-renders (updates).
Server Dispatcher: Used in React Fizz server rendering to implement hooks that support streaming server components.
Debug Dispatcher: Used by React DevTools to inspect hook state during component inspection.

Diagram: Hooks Dispatcher Pattern

Sources:

Hook Data Structure

Hooks are internally represented as linked list nodes attached to the fiber’s memoizedState. Each hook node tracks its current state and updates through the following structure:

memoizedState: The current state or value of the hook.
baseState and baseQueue: Used for maintaining correct state and update queue consistency especially under concurrent rendering.
queue: The update queue for hooks like useState or useReducer.
next: Reference to the next hook in the list.

Sources:

Mount vs. Update Paths

Mount Path

During the initial render, the mount dispatcher is active. For each hook call:

A new Hook node is created using createWorkInProgressHook().
The hook initializes its memoized state, refs, effects, or other internal values based on provided initial arguments.
Effect hooks schedule their effect objects on the fiber’s effect list.

Diagram: Hooks Mount Path

Sources:

Update Path

During an update render, React switches to the update dispatcher, which:

Retrieves the existing Hook node from the previous fiber via updateWorkInProgressHook().
Processes pending updates from the hook’s update queue to compute the new state.
Compares previous and new dependency arrays for effects to determine whether effects should re-run or be skipped.

Diagram: Hooks Update Path

Sources:

State Update Queue

Hooks that maintain state (useState, useReducer) use a circular linked list of update objects recording:

The lane (priority) for scheduling and concurrency.
The action representing the change (state or reducer action).
An eager state computed during dispatch to optimize bailing out of updates.

Sources:

`useActionState` and Form Integration

useActionState is a dedicated hook facilitating integration with React’s server and client form actions, previously known as useFormState.

Client-Side Implementation in ReactFiberHooks.js

useActionState maintains a state linked to a form action.
It initializes with the provided initial state and returns a dispatch function to run the associated action.
When dispatched, if the action returns a promise, it sets isPending state until resolved, then updates the state and requests a re-render.
The root fiber contains a formState object that manages the form-related state lifecycle including hydration packages/react-reconciler/src/ReactFiberHooks.js1700-1790 packages/react-reconciler/src/ReactFiberRoot.js110

Server-Side Implementation in ReactFizzHooks.js

The hook reads the form state snapshot from the current Request object’s formState.
It matches the hook index with the corresponding actionStateMatchingIndex in the server’s form state.
Returns the current form state for that action.
Dispatching on the server is a no-op as form actions run client-side or via the server action protocol.

Diagram: useActionState Lifecycle Flow on Client and Server

Sources:

Server-Side Hook Dispatchers (ReactFizzHooks)

The React Fizz server renderer uses a specialized hooks dispatcher in ReactFizzHooks.js optimized for streaming server components.

Key Characteristics

No Side Effects: Hooks like useEffect, useInsertionEffect, and useLayoutEffect are no-ops because no browser environment is involved packages/react-server/src/ReactFizzHooks.js300-310
State Hooks: useState and useReducer only establish initial state; updates are deferred and do not process on the server packages/react-server/src/ReactFizzHooks.js220-240
Deterministic IDs: useId generates consistent IDs for server/client hydration packages/react-server/src/ReactFizzHooks.js400-420
use: Supports suspension on thenables/promises for server components streaming packages/react-server/src/ReactFizzHooks.js430-490
useActionState: Reads from the server form state and provides a no-op dispatch packages/react-server/src/ReactFizzHooks.js500-550

Render Context Management

The server hooks maintain contextual variables such as:

currentlyRenderingComponent
currentlyRenderingTask
currentlyRenderingRequest
Hook linked lists (firstWorkInProgressHook and workInProgressHook)

before a server component render via the prepareToUseHooks function packages/react-server/src/ReactFizzHooks.js206-212

Sources:

Debug Tools API

React DevTools integrates via the react-debug-tools package utilizing a debug hooks dispatcher in ReactDebugHooks.js. This dispatcher wraps hook calls to collect detailed debug information.

Inspection Workflow

When DevTools requests inspection with inspectHooksOfFiber(fiber), it temporarily replaces the global hook dispatcher with the debug dispatcher.
The component is re-rendered under this debug dispatcher.
Each hook call is logged to a hookLog with debug info such as values, stack frames, and hook names packages/react-debug-tools/src/ReactDebugHooks.js40-140
The original dispatcher is restored after inspection.
DevTools renders the collected hook tree with states in its UI.

Diagram: DevTools Hooks Inspection Process

Sources:

Summary

React DevTools employs a debug hooks dispatcher to introspect hooks state, facilitating powerful developer tooling and inspection features.

This architecture balances concurrency, streaming rendering, seamless server/client integration, and robust debugging.

Hooks Implementation

Dispatcher Pattern

Dispatcher Implementations

Hook Data Structure

Mount vs. Update Paths

Mount Path

Update Path

State Update Queue

`useActionState` and Form Integration

Client-Side Implementation in ReactFiberHooks.js

Server-Side Implementation in ReactFizzHooks.js

Server-Side Hook Dispatchers (ReactFizzHooks)

Key Characteristics

Render Context Management

Debug Tools API

Inspection Workflow

Summary

References & Sources

On this page

Hooks Implementation

Dispatcher Pattern

Dispatcher Implementations

Hook Data Structure

Mount vs. Update Paths

Mount Path

Update Path

State Update Queue

`useActionState` and Form Integration

Client-Side Implementation in ReactFiberHooks.js

Server-Side Implementation in ReactFizzHooks.js

Server-Side Hook Dispatchers (ReactFizzHooks)

Key Characteristics

Render Context Management

Debug Tools API

Inspection Workflow

Summary

References & Sources

On this page

Hooks Implementation

Dispatcher Pattern

Dispatcher Implementations

Hook Data Structure

Mount vs. Update Paths

Mount Path

Update Path

State Update Queue

useActionState and Form Integration

Client-Side Implementation in ReactFiberHooks.js

Server-Side Implementation in ReactFizzHooks.js

Server-Side Hook Dispatchers (ReactFizzHooks)

Key Characteristics

Render Context Management

Debug Tools API

Inspection Workflow

Summary

References & Sources

On this page

Hooks Implementation

Dispatcher Pattern

Dispatcher Implementations

Hook Data Structure

Mount vs. Update Paths

Mount Path

Update Path

State Update Queue

useActionState and Form Integration

Client-Side Implementation in ReactFiberHooks.js

Server-Side Implementation in ReactFizzHooks.js

Server-Side Hook Dispatchers (ReactFizzHooks)

Key Characteristics

Render Context Management

Debug Tools API

Inspection Workflow

Summary

References & Sources

On this page

`useActionState` and Form Integration

`useActionState` and Form Integration