Fix `<Edit>`, `<ReferenceField>` and `<List>` to better support offline mode by fzaninotto · Pull Request #11161 · marmelab/react-admin

fzaninotto · 2026-02-12T17:19:45Z

Problem

Offline apps behave in a strange way, sometimes showing error pages even though they should not.

The offline mode of TanStack Query works fine in a standalone example, so the problems come from react-admin.

We lack a way to properly test offline mode, particularly in the context of a PWA.

Additional specific issues found:

<Edit> ignores the redirectOnError prop, making it hard to disable the redirection to the list in case of error (even if there's data in the cache)
<ReferenceField> renders an error message even if the reference record is available in the cache
<ListView> hides the pagination as soon as a fetch error occurs, preventing the user to go back to a page for which cached data are present

Solution

Build a demo (with Vite PWA plugin), track down the issues and fix them.

When offline, all calls to useQuery return an error... but they also return data.

In a nutshell, we must not only check for errors before deciding to show/return things but also that no data is available for offline support to work correctly

Fix ReferenceField
Fix ListView
Fix Edit
Test on a larger app (e.g. Atomic CRM)

If we have a NetworkError and valid data, it means we're offline and that TanStack query returned stale data.

How To Test

make build-offline
make preview-offline

(the offline mode doesn't work in dev mode, that's a limitation of vite-pwa)

Use the DevTools to simulate Offline mode when needed.

The PWA should be able to fetch data from the cache, even when reloading the whole app while offline (thanks to the service worker and the TanStack query Persister).

Known issue: TanStack query discards the cached data if you reload the app 2 times. See related issue.

The PWA should allow to perform mutations while offline, and replay the mutations when back online.

Note: Since this demo is hooked up to JSONPlaceholder API, the changes are not persisted for real. But the mutation should be visible in the Network tab and not trigger errors.

Additional Checks

The PR targets master for a bugfix or a documentation fix, or next for a feature
The PR includes unit tests (if not possible, describe why) -- debatable
The PR includes one or several stories (if not possible, describe why)
The documentation is up to date -- debatable

WiXSL · 2026-02-18T01:03:36Z

packages/ra-ui-materialui/src/field/ReferenceField.tsx

    const getRecordRepresentation = useGetRecordRepresentation(reference);

-    if (error) {
+    if (error && referenceRecord == null) {


When the app is online and a cached referenceRecord exists, it can hide real API errors

// Potencial Fix if (error && (referenceRecord == null || !referenceFieldContext.isPaused)) {

That's a good point but isPaused is not guaranteed to reflect the actual connectivity status all the time (it can take some time for the device to actually mark the connectivity status as offline in real-life conditions).

Besides, it can be argued that displaying the reference record is more useful to the user than displaying only the error, even if the data is not fresh.

Alternatively, we could also introduce a prop to let the user decide ultimately (just like we have a redirectOnError prop on <Edit> that can be set to false)...

@fzaninotto wdyt?

We're using the stale-while-revalidate approach heavily in react-admin, the idea being that the SPA architecture allows apps to be more useful to the user. Besides, there is still the possibility to both show the stale data and an error notification by using queryOptions.onError . So I think we can go with if (error && referenceRecord == null) { here.

fzaninotto · 2026-02-18T08:21:52Z

examples/ra-offline/README.md

@@ -0,0 +1,26 @@
+# ra-offline
+


deserves a one line explanation of the demo puropse and usage

fzaninotto · 2026-02-18T08:22:07Z

examples/ra-offline/package.json

+    "@tanstack/query-async-storage-persister": "^5.90.22",
+    "@tanstack/react-query": "^5.90.21",
+    "@tanstack/react-query-persist-client": "^5.90.22",
+    "ra-core": "^5.14.1",


not necessary (ra-ui-mui neither)

fzaninotto · 2026-02-18T08:22:46Z

examples/ra-offline/src/Layout.tsx

+export const Layout = ({ children }: { children: ReactNode }) => (
+  <RALayout>
+    {children}
+    <CheckForApplicationUpdate />


unnecessary. But we'd benefit from the react query dev tools

fzaninotto · 2026-02-18T08:23:17Z

examples/ra-offline/src/PostList.tsx

@@ -0,0 +1,14 @@
+import { DataTable, List, ReferenceField } from "react-admin";


no difference with a ListGuesser, we should remove it

fzaninotto · 2026-02-18T08:23:44Z

examples/ra-offline/index.html

+    <title>My Awesome App</title>
+    <meta name="description" content="My Awesome App description" />
+    <link rel="icon" href="/favicon.ico" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png" sizes="180x180" />


we can simplify by removing the favicons and loading css

fzaninotto · 2026-02-18T08:24:03Z

examples/ra-offline/package.json

+    "react": "^19.0.0",
+    "react-admin": "^5.14.1",
+    "react-dom": "^19.0.0",
+    "react-router": "^7.1.3",


same, not sure it's required

fzaninotto · 2026-02-18T08:24:39Z

examples/ra-offline/package.json

+    "eslint-plugin-react": "^7.37.4",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^16.0.0",
+    "https-localhost": "^4.7.1",


how is this used?

fzaninotto · 2026-02-18T08:26:28Z

yarn.lock

+  languageName: node
+  linkType: hard
+
+"@rollup/pluginutils@npm:^3.1.0":


some duplicates here, can we avoid them?

Not they are not duplicates, the major version is different (5 vs 3).

We can't avoid the two versions as one is needed by astro and the other one by the vite pwa plugin.

I already ran yarn dedupe btw so they should not remain any duplicates.

WiXSL · 2026-02-19T15:07:03Z

examples/ra-offline/package.json

+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview",
+    "serve": "REINSTALL=true PORT=4433 serve dist",


make serve-offline fails
serve Should be install in devDependencies

Actually I kept this command since it was added by @djhi and figured it was probably useful to force reinstalling the PWA on a real mobile device or something similar. But in the end, I did not use this command, force-reinstalling the PWA is easy enough to do with the desktop browser devtools (and on mobile device you can always remove and reinstall the app), so since it doesn't work I guess I'll simply remove it.

WiXSL

Other than the requested changes, I tested both in development and production (make build-offline + make preview-offline): offline behavior works as expected, including cached navigation/edit flows and mutation replay when reconnecting. Looks good to me.

Good Job 💪

WiXSL · 2026-02-19T15:54:25Z

examples/ra-offline/index.html

+    <link rel="apple-touch-icon" href="/apple-touch-icon-180x180.png" sizes="180x180" />
+    <link rel="mask-icon" href="/maskable-icon-512x512.png" color="#FFFFFF" />
+    <meta name="theme-color" content="#ffffff" />
+    <title>ra-offline</title>


Double title

nice catch!

Add an offline example

4b60676

fzaninotto added the WIP Work In Progress label Feb 12, 2026

slax57 added 8 commits February 17, 2026 10:26

update offline config according to doc

2e6440f

Merge remote-tracking branch 'origin/master' into offline-example

27c6538

disable redirectOnError in PostEdit

9a5133c

fix redirectOnError

a95ae3d

remove console.log

05d2c5b

revert package json files

20a1e6c

fix mutations

02fd89a

add offline example scripts to Makefile and package.json

219d1a5

vercel bot deployed to Preview – react-admin-storybook February 17, 2026 16:24 View deployment

slax57 added 2 commits February 17, 2026 17:26

yarn dedupe

c6f5ed1

remove ra packages duplicates

eca9991

slax57 approved these changes Feb 17, 2026

View reviewed changes

upgrade to codeql v3

dcc20bc

slax57 changed the title ~~Fix offline~~ Fix <Edit>, <ReferenceField> and <List> to better support offline mode Feb 17, 2026

vercel bot deployed to Preview – react-admin-storybook February 17, 2026 16:45 View deployment

slax57 added RFR Ready For Review WIP Work In Progress and removed WIP Work In Progress RFR Ready For Review labels Feb 17, 2026

manually fix yarn.lock

e40df52

vercel bot deployed to Preview – react-admin-storybook February 17, 2026 17:25 View deployment

slax57 added RFR Ready For Review and removed WIP Work In Progress labels Feb 17, 2026

slax57 mentioned this pull request Feb 17, 2026

MUI v7 – theme.alpha is not a function with React-Admin themes #11147

Closed

WiXSL requested changes Feb 18, 2026

View reviewed changes

fzaninotto commented Feb 18, 2026

View reviewed changes

slax57 added 2 commits February 18, 2026 10:01

improve demo readme

ca9d516

remove unnecessary deps

3a6eb4c

slax57 added 4 commits February 18, 2026 10:22

add tanstack query devtools

eec1044

replace PostList by ListGuesser

7c5a208

simplify index.html

49012c2

cleanup unnecessary deps

974d9b9

vercel bot deployed to Preview – react-admin-storybook February 18, 2026 09:38 View deployment

WiXSL requested changes Feb 19, 2026

View reviewed changes

WiXSL approved these changes Feb 19, 2026

View reviewed changes

WiXSL requested changes Feb 19, 2026

View reviewed changes

code review

5acd057

vercel bot deployed to Preview – react-admin-storybook February 20, 2026 13:23 View deployment

		@@ -0,0 +1,14 @@
		import { DataTable, List, ReferenceField } from "react-admin";

Uh oh!

Conversation

fzaninotto commented Feb 12, 2026 • edited by slax57 Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Problem

Solution

How To Test

Additional Checks

Uh oh!

WiXSL Feb 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WiXSL Feb 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

WiXSL left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

4 participants

Comments

fzaninotto commented Feb 12, 2026 •

edited by slax57

Loading

WiXSL Feb 18, 2026 •

edited

Loading

WiXSL Feb 19, 2026 •

edited

Loading

WiXSL left a comment •

edited

Loading