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.
// 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.
Syntax
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-onlyconvention 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.