Skip to content
Tutorials Center
My learning

Topics

React Reference ยท Top-Level React APIs

taintObjectReference and taintUniqueValue

Reference for React's experimental taint APIs: mark objects and secret values so they cannot be passed from Server Components to Client Components.

React's taint APIs are a safety net for Server Components. You mark a value as "must never reach the browser"; if some code later tries to pass it to a Client Component (or serialize it into the response), React throws an error on the server instead of leaking it.

Two functions exist: experimental_taintObjectReference for whole objects (such as a database row) and experimental_taintUniqueValue for single strings or numbers (such as an API key). Both are experimental: they are exported only from React's experimental channel and are not part of the stable react package, which is why the names start with experimental_. They are only meaningful inside a framework that supports Server Components.

JSX
// Server-only module, experimental React build
import {
  experimental_taintObjectReference as taintObjectReference,
  experimental_taintUniqueValue as taintUniqueValue,
} from 'react';

taintObjectReference('Do not pass the user record to the client.', user);
taintUniqueValue('Do not pass the API key to the client.', process, apiKey);

Try it

The live editor runs React in the browser and the stable build has no taint functions, so the first example only detects them. The second shows the idea with a small stand-in that is not React's implementation.

Feature detection
A stand-in that mimics the rule

Syntax

JSX
experimental_taintObjectReference(message, object)
experimental_taintUniqueValue(message, lifetime, value)

taintObjectReference

Name Description
message String used as the error text when the object is leaked.
object The object (or array, function) to taint. It must be an object, not a string.

taintUniqueValue

Name Description
message String used as the error text when the value is leaked.
lifetime An object that decides how long the value stays tainted, for example process for a value that lives for the whole server process. The taint is removed when that object is garbage collected.
value A string, bigint or typed array. Pass values that are unique to your secret, not everyday strings.

Both return undefined. When a tainted value is passed to a Client Component or otherwise serialized for the client, React throws an error containing message.

Usage notes

  • Taint what you already treat as secret: database rows with password hashes, session tokens, API keys, internal IDs you never want exposed.
  • Object taint is by reference. Copying a property out (user.name) or spreading ({ ...user }) creates a new, untainted value. It catches accidents like <Profile user={user} />, not deliberate leaks.
  • Unique-value taint is by value and only meant for values that look random, such as keys and tokens. Derived values (a substring, a hash, an encoded copy) are not tracked.
  • It is defense in depth, never a replacement for a data access layer that returns only the fields a component needs.
  • Pair it with the server-only convention so secret-handling modules cannot be imported by client code at all.
  • Because the API is experimental, names and behavior may change. Check your framework's documentation before relying on it; many apps skip it and use narrow data transfer objects instead.