20/02/2025, 09:07 cache – React

v19

API REFERENCE APIS

cache

React Server Components

cache is only for use with React Server Components.

cache lets you cache the result of a data fetch or computation.

const cachedFn = cache(fn);

Reference

cache(fn)

Usage

Cache an expensive computation

Share a snapshot of data
Preload data

Troubleshooting

My memoized function still runs even though I’ve called it with the
same arguments

Reference

cache(fn)

https://react.dev/reference/react/cache 1/13
20/02/2025, 09:07 cache – React

Call cache outside of any components to create a version of the function

with caching.

import {cache} from 'react';

import calculateMetrics from 'lib/metrics';

const getMetrics = cache(calculateMetrics);

function Chart({data}) {
const report = getMetrics(data);
// ...
}

When getMetrics is first called with data , getMetrics will call

calculateMetrics(data) and store the result in cache. If getMetrics is

called again with the same data , it will return the cached result instead of
calling calculateMetrics(data) again.

See more examples below.

Parameters

fn : The function you want to cache results for. fn can take any
arguments and return any value.

Returns

cache returns a cached version of fn with the same type signature. It does

not call fn in the process.

When calling cachedFn with given arguments, it first checks if a cached

result exists in the cache. If a cached result exists, it returns the result. If not,
it calls fn with the arguments, stores the result in the cache, and returns the
result. The only time fn is called is when there is a cache miss.

Note
https://react.dev/reference/react/cache 2/13
20/02/2025, 09:07 cache – React

The optimization of caching return values based on inputs is known

as memoization. We refer to the function returned from cache as a
memoized function.

Caveats

React will invalidate the cache for all memoized functions for each server
request.
Each call to cache creates a new function. This means that calling cache
with the same function multiple times will return different memoized
functions that do not share the same cache.
cachedFn will also cache errors. If fn throws an error for certain
arguments, it will be cached, and the same error is re-thrown when
cachedFn is called with those same arguments.

cache is for use in Server Components only.

Usage

Cache an expensive computation

Use cache to skip duplicate work.

import {cache} from 'react';

import calculateUserMetrics from 'lib/user';

const getUserMetrics = cache(calculateUserMetrics);

function Profile({user}) {
const metrics = getUserMetrics(user) ;
// ...
}

function TeamReport({users}) {
for (let user in users) {

https://react.dev/reference/react/cache 3/13
20/02/2025, 09:07 cache – React

const metrics = getUserMetrics(user) ;

// ...
}
// ...
}

If the same user object is rendered in both Profile and TeamReport , the
two components can share work and only call calculateUserMetrics once
for that user .

Assume Profile is rendered first. It will call getUserMetrics , and check if

there is a cached result. Since it is the first time getUserMetrics is called
with that user , there will be a cache miss. getUserMetrics will then call
calculateUserMetrics with that user and write the result to cache.

When TeamReport renders its list of users and reaches the same user
object, it will call getUserMetrics and read the result from cache.

Pitfall

Calling different memoized functions will read from different

caches.

To access the same cache, components must call the same

memoized function.

// Temperature.js
import {cache} from 'react';
import {calculateWeekReport} from './report';

export function Temperature({cityData}) {

// 🚩 Wrong: Calling `cache` in component creates new `getWeek
const getWeekReport = cache(calculateWeekReport) ;
const report = getWeekReport (cityData);
// ...

https://react.dev/reference/react/cache 4/13
20/02/2025, 09:07 cache – React

// Precipitation.js
import {cache} from 'react';
import {calculateWeekReport} from './report';

// 🚩 Wrong: `getWeekReport` is only accessible for `Precipitation

const getWeekReport = cache(calculateWeekReport) ;

export function Precipitation({cityData}) {

const report = getWeekReport (cityData);
// ...
}

In the above example, Precipitation and Temperature each call

cache to create a new memoized function with their own cache look-

up. If both components render for the same cityData , they will do
duplicate work to call calculateWeekReport .

In addition, Temperature creates a new memoized function each

time the component is rendered which doesn’t allow for any cache
sharing.

To maximize cache hits and reduce work, the two components

should call the same memoized function to access the same cache.
Instead, define the memoized function in a dedicated module that
can be import -ed across components.

// getWeekReport.js
import {cache} from 'react';
import {calculateWeekReport} from './report';

export default cache(calculateWeekReport) ;

// Temperature.js

https://react.dev/reference/react/cache 5/13
20/02/2025, 09:07 cache – React

import getWeekReport from './getWeekReport';

export default function Temperature({cityData}) {

const report = getWeekReport (cityData);
// ...
}

// Precipitation.js
import getWeekReport from './getWeekReport';

export default function Precipitation({cityData}) {

const report = getWeekReport (cityData);
// ...
}

Here, both components call the same memoized function exported

from ./getWeekReport.js to read and write to the same cache.

Share a snapshot of data

To share a snapshot of data between components, call cache with a data-

fetching function like fetch . When multiple components make the same
data fetch, only one request is made and the data returned is cached and
shared across components. All components refer to the same snapshot of
data across the server render.

import {cache} from 'react';

import {fetchTemperature} from './api.js';

const getTemperature = cache(async ( city ) => {

return await fetchTemperature(city) ;
});

async function AnimatedWeatherCard({city}) {

const temperature = await getTemperature ( city );
// ...
https://react.dev/reference/react/cache 6/13
20/02/2025, 09:07 cache – React

async function MinimalWeatherCard({city}) {

const temperature = await getTemperature ( city );
// ...
}

If AnimatedWeatherCard and MinimalWeatherCard both render for the same

city , they will receive the same snapshot of data from the memoized
function .

If AnimatedWeatherCard and MinimalWeatherCard supply different city

arguments to getTemperature , then fetchTemperature will be called twice
and each call site will receive different data.

The city acts as a cache key.

Note

Asynchronous rendering is only supported for Server Components.

async function AnimatedWeatherCard({city}) {

const temperature = await getTemperature(city);
// ...
}

Preload data

By caching a long-running data fetch, you can kick off asynchronous work
prior to rendering the component.

const getUser = cache(async (id) => {

https://react.dev/reference/react/cache 7/13
20/02/2025, 09:07 cache – React

return await db.user.query(id);

});

async function Profile({id}) {

const user = await getUser(id) ;
return (
<section>
<img src={user.profilePic} />
<h2>{user.name}</h2>
</section>
);
}

function Page({id}) {
// ✅ Good: start fetching the user data
getUser(id) ;
// ... some computational work
return (
<>
<Profile id={id} />
</>
);
}

When rendering Page , the component calls getUser but note that it
doesn’t use the returned data. This early getUser call kicks off the
asynchronous database query that occurs while Page is doing other
computational work and rendering children.

When rendering Profile , we call getUser again. If the initial getUser call
has already returned and cached the user data, when Profile asks and
waits for this data , it can simply read from the cache without requiring
another remote procedure call. If the initial data request hasn’t been
completed, preloading data in this pattern reduces delay in data-fetching.

DEEP DIVE

Caching asynchronous work

https://react.dev/reference/react/cache 8/13
20/02/2025, 09:07 cache – React

Show Details

Pitfall

Calling a memoized function outside of a component will not use

the cache.

import {cache} from 'react';

const getUser = cache(async (userId) => {

return await db.user.query(userId);
});

// 🚩 Wrong: Calling memoized function outside of component will n

getUser('demo-id');

async function DemoProfile() {

// ✅ Good: `getUser` will memoize.
const user = await getUser('demo-id');
return <Profile user={user} />;
}

React only provides cache access to the memoized function in a

component. When calling getUser outside of a component, it will
still evaluate the function but not read or update the cache.

This is because cache access is provided through a context which is

only accessible from a component.

https://react.dev/reference/react/cache 9/13
20/02/2025, 09:07 cache – React

DEEP DIVE

When should I use cache , memo , or useMemo ?

Show Details

Troubleshooting

My memoized function still runs even though I’ve

called it with the same arguments

See prior mentioned pitfalls

Calling different memoized functions will read from different caches.

Calling a memoized function outside of a component will not use the
cache.

If none of the above apply, it may be a problem with how React checks if
something exists in cache.

If your arguments are not primitives (ex. objects, functions, arrays), ensure
you’re passing the same object reference.

When calling a memoized function, React will look up the input arguments to
see if a result is already cached. React will use shallow equality of the
arguments to determine if there is a cache hit.

import {cache} from 'react';

const calculateNorm = cache((vector) => {

// ...
});

https://react.dev/reference/react/cache 10/13
20/02/2025, 09:07 cache – React

function MapMarker(props) {
// 🚩 Wrong: props is an object that changes every render.
const length = calculateNorm(props);
// ...
}

function App() {
return (
<>
<MapMarker x={10} y={10} z={10} />
<MapMarker x={10} y={10} z={10} />
</>
);
}

In this case the two MapMarker s look like they’re doing the same work and
calling calculateNorm with the same value of {x: 10, y: 10, z:10} . Even
though the objects contain the same values, they are not the same object
reference as each component creates its own props object.

React will call Object.is on the input to verify if there is a cache hit.

import {cache} from 'react';

const calculateNorm = cache((x, y, z) => {

// ...
});

function MapMarker(props) {
// ✅ Good: Pass primitives to memoized function
const length = calculateNorm(props.x, props.y, props.z);
// ...
}

function App() {
return (
<>
<MapMarker x={10} y={10} z={10} />
<MapMarker x={10} y={10} z={10} />
</>
);

https://react.dev/reference/react/cache 11/13
20/02/2025, 09:07 cache – React

One way to address this could be to pass the vector dimensions to

calculateNorm . This works because the dimensions themselves are

primitives.

Another solution may be to pass the vector object itself as a prop to the
component. We’ll need to pass the same object to both component
instances.

import {cache} from 'react';

const calculateNorm = cache((vector) => {

// ...
});

function MapMarker(props) {
// ✅ Good: Pass the same `vector` object
const length = calculateNorm(props.vector);
// ...
}

function App() {
const vector = [10, 10, 10];
return (
<>
<MapMarker vector={vector} />
<MapMarker vector={vector} />
</>
);
}

PREVIOUS

act

NEXT

https://react.dev/reference/react/cache 12/13
20/02/2025, 09:07 cache – React

createContext

Copyright © Meta Platforms, Inc

uwu?

Learn React API Reference

Quick Start React APIs

Installation React DOM APIs

Describing the UI

Adding Interactivity

Managing State

Escape Hatches

Community More

Code of Conduct Blog

Meet the Team React Native

Docs Contributors Privacy

Acknowledgements Terms

https://react.dev/reference/react/cache 13/13