Add offline support to <ReferenceManyCountBase> and <ReferenceManyCount>

djhi · djhi · commit e8764c69f6b5 · 2025-08-27T16:52:35.000+02:00
diff --git a/docs/ReferenceManyCount.md b/docs/ReferenceManyCount.md
@@ -68,6 +68,7 @@ export const PostList = () => (
 | `target`    | Required | string                                     | -                                 | Name of the field in the related resource that points to the current one. |
 | `filter`    | Optional | Object                                     | -                                 | Filter to apply to the query.                                             |
 | `link`      | Optional | bool                                       | `false`                           | If true, the count is wrapped in a `<Link>` to the filtered list view.    |
+| `offline`   | Optional | `ReactNode`                                |                                   | The component to render when there is no connectivity and the record isn't in the cache
 | `resource`  | Optional | string                                     | -                                 | Resource to count. Default to the current `ResourceContext`               |
 | `sort`      | Optional | `{ field: string, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`  | The sort option sent to `getManyReference`                                |
 | `timeout`   | Optional | number                                     | 1000                              | Number of milliseconds to wait before displaying the loading indicator.   |
@@ -118,6 +119,22 @@ When used in conjunction to the `filter` prop, the link will point to the list v
 ```
 {% endraw %}
 
+## `offline`
+
+By default, `<ReferenceManyCount>` renders the `<Offline variant="inline">` component when there is no connectivity and the count hasn't been cached yet. You can provide your own component via the `offline` prop:
+
+```jsx
+<ReferenceManyCount
+    reference="comments"
+    target="post_id"
+    offline={
+        <Alert severity="warning">
+            You are offline, data cannot be loaded
+        </Alert>
+    }
+/>
+```
+
 ## `reference`
 
 The `reference` prop is required and must be the name of the related resource to fetch. For instance, to fetch the number of comments related to the current post:
diff --git a/packages/ra-core/src/controller/field/ReferenceManyCountBase.spec.tsx b/packages/ra-core/src/controller/field/ReferenceManyCountBase.spec.tsx
@@ -0,0 +1,44 @@
+import * as React from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import {
+    Basic,
+    ErrorState,
+    LoadingState,
+    Offline,
+} from './ReferenceManyCountBase.stories';
+
+describe('ReferenceManyCountBase', () => {
+    it('should display an error if error is defined', async () => {
+        jest.spyOn(console, 'error')
+            .mockImplementationOnce(() => {})
+            .mockImplementationOnce(() => {});
+
+        render(<ErrorState />);
+        await screen.findByText('Error!');
+    });
+
+    it('should display the loading state', async () => {
+        render(<LoadingState />);
+        await screen.findByText('loading...', undefined, { timeout: 2000 });
+    });
+
+    it('should render the total', async () => {
+        render(<Basic />);
+        await screen.findByText('3');
+    });
+
+    it('should render the offline prop node when offline', async () => {
+        render(<Offline />);
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        fireEvent.click(await screen.findByText('Toggle Child'));
+        await screen.findByText('You are offline, cannot load data');
+        fireEvent.click(await screen.findByText('Simulate online'));
+        await screen.findByText('3');
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        expect(
+            screen.queryByText('You are offline, cannot load data')
+        ).toBeNull();
+        await screen.findByText('3');
+        fireEvent.click(await screen.findByText('Simulate online'));
+    });
+});
diff --git a/packages/ra-core/src/controller/field/ReferenceManyCountBase.stories.tsx b/packages/ra-core/src/controller/field/ReferenceManyCountBase.stories.tsx
@@ -1,8 +1,12 @@
 import * as React from 'react';
-import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import {
+    QueryClientProvider,
+    QueryClient,
+    onlineManager,
+} from '@tanstack/react-query';
 import { RecordContextProvider } from '../record';
 import { DataProviderContext } from '../../dataProvider';
-import { ResourceContextProvider } from '../../core';
+import { ResourceContextProvider, useIsOffline } from '../../core';
 import { TestMemoryRouter } from '../../routing';
 import { ReferenceManyCountBase } from './ReferenceManyCountBase';
 
@@ -141,3 +145,57 @@ export const Slow = () => (
         />
     </Wrapper>
 );
+
+export const Offline = () => {
+    return (
+        <Wrapper
+            dataProvider={{
+                getManyReference: () =>
+                    Promise.resolve({
+                        data: [comments.filter(c => c.post_id === 1)[0]],
+                        total: comments.filter(c => c.post_id === 1).length,
+                    }),
+            }}
+        >
+            <div>
+                <RenderChildOnDemand>
+                    <ReferenceManyCountBase
+                        reference="comments"
+                        target="post_id"
+                        loading="Loading..."
+                        offline={
+                            <span style={{ color: 'orange' }}>
+                                You are offline, cannot load data
+                            </span>
+                        }
+                    />
+                </RenderChildOnDemand>
+            </div>
+            <SimulateOfflineButton />
+        </Wrapper>
+    );
+};
+
+const SimulateOfflineButton = () => {
+    const isOffline = useIsOffline();
+    return (
+        <button
+            type="button"
+            onClick={() => onlineManager.setOnline(isOffline)}
+        >
+            {isOffline ? 'Simulate online' : 'Simulate offline'}
+        </button>
+    );
+};
+
+const RenderChildOnDemand = ({ children }) => {
+    const [showChild, setShowChild] = React.useState(false);
+    return (
+        <>
+            <button onClick={() => setShowChild(!showChild)}>
+                Toggle Child
+            </button>
+            {showChild && <div>{children}</div>}
+        </>
+    );
+};
diff --git a/packages/ra-core/src/controller/field/ReferenceManyCountBase.tsx b/packages/ra-core/src/controller/field/ReferenceManyCountBase.tsx
@@ -17,10 +17,11 @@ import { useTimeout } from '../../util/hooks';
  * <ReferenceManyCountBase reference="comments" target="post_id" filter={{ is_published: true }} />
  */
 export const ReferenceManyCountBase = (props: ReferenceManyCountBaseProps) => {
-    const { loading = null, error = null, timeout = 1000, ...rest } = props;
+    const { loading, error, offline, timeout = 1000, ...rest } = props;
     const oneSecondHasPassed = useTimeout(timeout);
 
     const {
+        isPaused,
         isPending,
         error: fetchError,
         total,
@@ -30,15 +31,24 @@ export const ReferenceManyCountBase = (props: ReferenceManyCountBaseProps) => {
         perPage: 1,
     });
 
+    const shouldRenderLoading =
+        isPending && !isPaused && loading !== undefined && loading !== false;
+    const shouldRenderOffline =
+        isPending && isPaused && offline !== undefined && offline !== false;
+    const shouldRenderError =
+        !isPending && fetchError && error !== undefined && error !== false;
+
     return (
         <>
-            {isPending
+            {shouldRenderLoading
                 ? oneSecondHasPassed
                     ? loading
                     : null
-                : fetchError
-                  ? error
-                  : total}
+                : shouldRenderOffline
+                  ? offline
+                  : shouldRenderError
+                    ? error
+                    : total}
         </>
     );
 };
@@ -48,4 +58,5 @@ export interface ReferenceManyCountBaseProps
     timeout?: number;
     loading?: React.ReactNode;
     error?: React.ReactNode;
+    offline?: React.ReactNode;
 }
diff --git a/packages/ra-ui-materialui/src/field/ReferenceManyCount.spec.tsx b/packages/ra-ui-materialui/src/field/ReferenceManyCount.spec.tsx
@@ -1,9 +1,10 @@
 import * as React from 'react';
-import { render, screen } from '@testing-library/react';
+import { fireEvent, render, screen } from '@testing-library/react';
 
 import {
     Basic,
     ErrorState,
+    Offline,
     Themed,
     WithFilter,
     Wrapper,
@@ -52,4 +53,19 @@ describe('<ReferenceManyCount />', () => {
         render(<Themed />);
         expect(screen.getByTestId('themed')).toBeDefined();
     });
+
+    it('should render the offline prop node when offline', async () => {
+        render(<Offline />);
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        fireEvent.click(await screen.findByText('Toggle Child'));
+        await screen.findByText('No connectivity. Could not fetch data.');
+        fireEvent.click(await screen.findByText('Simulate online'));
+        await screen.findByText('3');
+        fireEvent.click(await screen.findByText('Simulate offline'));
+        expect(
+            screen.queryByText('No connectivity. Could not fetch data.')
+        ).toBeNull();
+        await screen.findByText('3');
+        fireEvent.click(await screen.findByText('Simulate online'));
+    });
 });
diff --git a/packages/ra-ui-materialui/src/field/ReferenceManyCount.stories.tsx b/packages/ra-ui-materialui/src/field/ReferenceManyCount.stories.tsx
@@ -1,10 +1,15 @@
 import * as React from 'react';
-import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
+import {
+    QueryClientProvider,
+    QueryClient,
+    onlineManager,
+} from '@tanstack/react-query';
 import {
     DataProviderContext,
     RecordContextProvider,
     ResourceContextProvider,
     TestMemoryRouter,
+    useIsOffline,
 } from 'ra-core';
 import { deepmerge } from '@mui/utils';
 import { createTheme, ThemeOptions } from '@mui/material';
@@ -238,3 +243,44 @@ export const Themed = () => (
         <ReferenceManyCount reference="comments" target="post_id" />
     </Wrapper>
 );
+
+export const Offline = () => (
+    <Wrapper
+        dataProvider={{
+            getManyReference: () =>
+                Promise.resolve({
+                    data: [comments.filter(c => c.post_id === 1)[0]],
+                    total: comments.filter(c => c.post_id === 1).length,
+                }),
+        }}
+    >
+        <RenderChildOnDemand>
+            <ReferenceManyCount reference="comments" target="post_id" />
+        </RenderChildOnDemand>
+        <SimulateOfflineButton />
+    </Wrapper>
+);
+
+const SimulateOfflineButton = () => {
+    const isOffline = useIsOffline();
+    return (
+        <button
+            type="button"
+            onClick={() => onlineManager.setOnline(isOffline)}
+        >
+            {isOffline ? 'Simulate online' : 'Simulate offline'}
+        </button>
+    );
+};
+
+const RenderChildOnDemand = ({ children }) => {
+    const [showChild, setShowChild] = React.useState(false);
+    return (
+        <>
+            <button onClick={() => setShowChild(!showChild)}>
+                Toggle Child
+            </button>
+            {showChild && <div>{children}</div>}
+        </>
+    );
+};
diff --git a/packages/ra-ui-materialui/src/field/ReferenceManyCount.tsx b/packages/ra-ui-materialui/src/field/ReferenceManyCount.tsx
@@ -3,8 +3,8 @@ import {
     useRecordContext,
     useCreatePath,
     ReferenceManyCountBase,
-    SortPayload,
     RaRecord,
+    ReferenceManyCountBaseProps,
 } from 'ra-core';
 import clsx from 'clsx';
 import { Typography, TypographyProps, CircularProgress } from '@mui/material';
@@ -19,6 +19,7 @@ import get from 'lodash/get';
 import { FieldProps } from './types';
 import { sanitizeFieldRestProps } from './sanitizeFieldRestProps';
 import { Link } from '../Link';
+import { Offline } from '../Offline';
 
 /**
  * Fetch and render the number of records related to the current one
@@ -51,6 +52,7 @@ export const ReferenceManyCount = <RecordType extends RaRecord = RaRecord>(
         link,
         resource,
         source = 'id',
+        offline = defaultOffline,
         ...rest
     } = props;
     const record = useRecordContext(props);
@@ -63,6 +65,7 @@ export const ReferenceManyCount = <RecordType extends RaRecord = RaRecord>(
             error={
                 <ErrorIcon color="error" fontSize="small" titleAccess="error" />
             }
+            offline={offline}
         />
     );
     return (
@@ -98,17 +101,14 @@ export const ReferenceManyCount = <RecordType extends RaRecord = RaRecord>(
 
 // This is a hack that replaces react support for defaultProps. We currently need this for the Datagrid.
 ReferenceManyCount.textAlign = 'right';
+const defaultOffline = <Offline variant="inline" />;
 
 export interface ReferenceManyCountProps<RecordType extends RaRecord = RaRecord>
     extends Omit<FieldProps<RecordType>, 'source'>,
+        Omit<ReferenceManyCountBaseProps, 'source' | 'record'>,
         Omit<TypographyProps, 'textAlign'> {
-    reference: string;
     source?: string;
-    target: string;
-    sort?: SortPayload;
-    filter?: any;
     link?: boolean;
-    timeout?: number;
 }
 
 const PREFIX = 'RaReferenceManyCount';
