Add offline support to <InfiniteListBase> and <InfiniteList>

djhi · djhi · commit 0678a7ef3d9e · 2025-08-28T14:58:29.000+02:00
diff --git a/docs/InfiniteList.md b/docs/InfiniteList.md
@@ -72,6 +72,7 @@ The props are the same as [the `<List>` component](./List.md):
 | `filters`                  | Optional | `ReactElement` | -                       | The filters to display in the toolbar.                                                       |
 | `filter`                   | Optional | `object`       | -                       | The permanent filter values.                                                                 |
 | `filter DefaultValues`     | Optional | `object`       | -                       | The default filter values.                                                                   |
+| `offline`                  | Optional | `ReactNode`    | `<Offline>`             | The component to render when there is no connectivity and there is no data in the cache      |
 | `pagination`               | Optional | `ReactElement` | `<Infinite Pagination>` | The pagination component to use.                                                             |
 | `perPage`                  | Optional | `number`       | `10`                    | The number of records to fetch per page.                                                     |
 | `queryOptions`             | Optional | `object`       | -                       | The options to pass to the `useQuery` hook.                                                  |
@@ -85,6 +86,49 @@ Check the [`<List>` component](./List.md) for details about each prop.
 
 Additional props are passed down to the root component (a MUI `<Card>` by default).
 
+## `offline`
+
+By default, `<List>` renders the `<Offline>` component when there is no connectivity and there are no records in the cache yet for the current parameters (page, sort, etc.). You can provide your own component via the `offline` prop:
+
+```jsx
+import { InfiniteList, InfinitePagination } from 'react-admin';
+import { Alert } from '@mui/material';
+
+const offline = <Alert severity="warning">No network. Could not load the posts.</Alert>;
+// The offline component may be displayed at the bottom of the page if the network connectivity is lost
+// when loading new pages. Make sure you pass your custom offline component here too
+const pagination = <InfinitePagination offline={offline} />;
+
+export const PostList = () => (
+    <InfiniteList offline={offline} pagination={pagination}>
+        ...
+    </InfiniteList>
+);
+```
+
+**Tip**: If the record is in the Tanstack Query cache but you want to warn the user that they may see an outdated version, you can use the `<IsOffline>` component:
+
+```jsx
+import { InfiniteList, InfinitePagination, IsOffline } from 'react-admin';
+import { Alert } from '@mui/material';
+
+const offline = <Alert severity="warning">No network. Could not load the posts.</Alert>;
+// The offline component may be displayed at the bottom of the page if the network connectivity is lost
+// when loading new pages. Make sure you pass your custom offline component here too
+const pagination = <InfinitePagination offline={offline} />;
+
+export const PostList = () => (
+    <InfiniteList offline={offline} pagination={pagination}>
+        <IsOffline>
+           <Alert severity="warning">
+                You are offline, the data may be outdated
+            </Alert>
+        </IsOffline>
+        ...
+    </InfiniteList>
+);
+```
+
 ## `pagination`
 
 You can replace the default "load on scroll" pagination (triggered by a component named `<InfinitePagination>`) by a custom pagination component. To get the pagination state and callbacks, you'll need to read the `InfinitePaginationContext`.
diff --git a/packages/ra-core/src/controller/list/InfiniteListBase.stories.tsx b/packages/ra-core/src/controller/list/InfiniteListBase.stories.tsx
@@ -3,17 +3,20 @@ import fakeRestProvider from 'ra-data-fakerest';
 import englishMessages from 'ra-language-english';
 import frenchMessages from 'ra-language-french';
 import polyglotI18nProvider from 'ra-i18n-polyglot';
-import { InfiniteListBase } from './InfiniteListBase';
+import { InfiniteListBase, InfiniteListBaseProps } from './InfiniteListBase';
 import { CoreAdminContext } from '../../core';
 import { useListContext } from './useListContext';
 import { useInfinitePaginationContext } from './useInfinitePaginationContext';
 import {
     AuthProvider,
     DataProvider,
     I18nProvider,
+    IsOffline,
     mergeTranslations,
+    TestMemoryRouter,
     useLocaleState,
 } from '../..';
+import { onlineManager } from '@tanstack/react-query';
 
 export default {
     title: 'ra-core/controller/list/InfiniteListBase',
@@ -314,6 +317,93 @@ export const WithRenderProps = () => (
     </CoreAdminContext>
 );
 
+export const Offline = ({
+    dataProvider = defaultDataProvider,
+    isOnline = true,
+    ...props
+}: {
+    dataProvider?: DataProvider;
+    isOnline?: boolean;
+} & Partial<InfiniteListBaseProps>) => {
+    React.useEffect(() => {
+        onlineManager.setOnline(isOnline);
+    }, [isOnline]);
+    return (
+        <TestMemoryRouter>
+            <CoreAdminContext dataProvider={dataProvider}>
+                <InfiniteListBase
+                    resource="books"
+                    perPage={5}
+                    {...props}
+                    offline={<p>You are offline, cannot load data</p>}
+                    render={controllerProps => {
+                        const {
+                            data,
+                            error,
+                            isPending,
+                            page,
+                            perPage,
+                            setPage,
+                            total,
+                        } = controllerProps;
+                        if (isPending) {
+                            return <div>Loading...</div>;
+                        }
+                        if (error) {
+                            return <div>Error...</div>;
+                        }
+
+                        return (
+                            <div>
+                                <p>
+                                    Use the story controls to simulate offline
+                                    mode:
+                                </p>
+                                <IsOffline>
+                                    <p style={{ color: 'orange' }}>
+                                        You are offline, the data may be
+                                        outdated
+                                    </p>
+                                </IsOffline>
+                                <button
+                                    disabled={page <= 1}
+                                    onClick={() => setPage(page - 1)}
+                                >
+                                    previous
+                                </button>
+                                <span>
+                                    Page {page} of {Math.ceil(total / perPage)}
+                                </span>
+                                <button
+                                    disabled={page >= total / perPage}
+                                    onClick={() => setPage(page + 1)}
+                                >
+                                    next
+                                </button>
+                                <ul>
+                                    {data.map((record: any) => (
+                                        <li key={record.id}>{record.title}</li>
+                                    ))}
+                                </ul>
+                            </div>
+                        );
+                    }}
+                />
+            </CoreAdminContext>
+        </TestMemoryRouter>
+    );
+};
+
+Offline.args = {
+    isOnline: true,
+};
+
+Offline.argTypes = {
+    isOnline: {
+        control: { type: 'boolean' },
+    },
+};
+
 const Title = () => {
     const { defaultTitle } = useListContext();
     const [locale, setLocale] = useLocaleState();
diff --git a/packages/ra-core/src/controller/list/InfiniteListBase.tsx b/packages/ra-core/src/controller/list/InfiniteListBase.tsx
@@ -48,7 +48,8 @@ import { useIsAuthPending } from '../../auth';
 export const InfiniteListBase = <RecordType extends RaRecord = any>({
     children,
     render,
-    loading = null,
+    loading,
+    offline,
     ...props
 }: InfiniteListBaseProps<RecordType>) => {
     const controllerProps = useInfiniteListController<RecordType>(props);
@@ -57,16 +58,27 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
         action: 'list',
     });
 
-    if (isAuthPending && !props.disableAuthentication) {
-        return loading;
-    }
-
     if (!render && !children) {
         throw new Error(
             "<InfiniteListBase> requires either a 'render' prop or 'children' prop"
         );
     }
 
+    const showLoading =
+        isAuthPending &&
+        !props.disableAuthentication &&
+        loading !== undefined &&
+        loading !== false;
+
+    const { isPaused, isPending, isPlaceholderData } = controllerProps;
+    const showOffline =
+        isPaused &&
+        // If isPending and isPaused are true, we are offline and couldn't even load the initial data
+        // If isPaused and isPlaceholderData are true, we are offline and couldn't even load data with different parameters on the same useQuery observer
+        (isPending || isPlaceholderData) &&
+        offline !== undefined &&
+        offline !== false;
+
     return (
         // We pass props.resource here as we don't need to create a new ResourceContext if the props is not provided
         <OptionalResourceContextProvider value={props.resource}>
@@ -82,7 +94,13 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
                             controllerProps.isFetchingPreviousPage,
                     }}
                 >
-                    {render ? render(controllerProps) : children}
+                    {showLoading
+                        ? loading
+                        : showOffline
+                          ? offline
+                          : render
+                            ? render(controllerProps)
+                            : children}
                 </InfinitePaginationContext.Provider>
             </ListContextProvider>
         </OptionalResourceContextProvider>
@@ -93,5 +111,6 @@ export interface InfiniteListBaseProps<RecordType extends RaRecord = any>
     extends InfiniteListControllerProps<RecordType> {
     loading?: ReactNode;
     children?: ReactNode;
+    offline?: ReactNode;
     render?: (props: InfiniteListControllerResult<RecordType>) => ReactNode;
 }
diff --git a/packages/ra-core/src/controller/list/useInfiniteListController.ts b/packages/ra-core/src/controller/list/useInfiniteListController.ts
@@ -102,7 +102,9 @@ export const useInfiniteListController = <
         total,
         error,
         isLoading,
+        isPaused,
         isPending,
+        isPlaceholderData,
         isFetching,
         hasNextPage,
         hasPreviousPage,
@@ -204,7 +206,9 @@ export const useInfiniteListController = <
         hideFilter: queryModifiers.hideFilter,
         isFetching,
         isLoading,
+        isPaused,
         isPending,
+        isPlaceholderData,
         onSelect: selectionModifiers.select,
         onSelectAll,
         onToggleItem: selectionModifiers.toggle,
diff --git a/packages/ra-ui-materialui/src/list/InfiniteList.stories.tsx b/packages/ra-ui-materialui/src/list/InfiniteList.stories.tsx
@@ -7,8 +7,16 @@ import {
     useListContext,
     useInfinitePaginationContext,
     TestMemoryRouter,
+    IsOffline,
 } from 'ra-core';
-import { Box, Button, Card, ThemeOptions, Typography } from '@mui/material';
+import {
+    Alert,
+    Box,
+    Button,
+    Card,
+    ThemeOptions,
+    Typography,
+} from '@mui/material';
 import { InfiniteList } from './InfiniteList';
 import { SimpleList } from './SimpleList';
 import { DataTable, type DataTableProps } from './datatable';
@@ -24,6 +32,7 @@ import { TopToolbar, Layout } from '../layout';
 import { BulkActionsToolbar } from './BulkActionsToolbar';
 import { deepmerge } from '@mui/utils';
 import { defaultLightTheme } from '../theme';
+import { onlineManager } from '@tanstack/react-query';
 
 export default {
     title: 'ra-ui-materialui/list/InfiniteList',
@@ -522,3 +531,82 @@ export const WithRenderProp = () => (
         />
     </Admin>
 );
+
+export const Offline = ({
+    isOnline = true,
+    offline,
+    pagination,
+}: {
+    isOnline?: boolean;
+    offline?: React.ReactNode;
+    pagination?: React.ReactNode;
+}) => {
+    React.useEffect(() => {
+        onlineManager.setOnline(isOnline);
+    }, [isOnline]);
+    return (
+        <Admin dataProvider={dataProvider}>
+            <Resource
+                name="books"
+                list={() => (
+                    <InfiniteList offline={offline} pagination={pagination}>
+                        <BookListOffline />
+                    </InfiniteList>
+                )}
+            />
+        </Admin>
+    );
+};
+
+const BookListOffline = () => {
+    const { error, isPending } = useListContext();
+    if (isPending) {
+        return <div>Loading...</div>;
+    }
+    if (error) {
+        return <div>Error: {error.message}</div>;
+    }
+    return (
+        <>
+            <IsOffline>
+                <Alert severity="warning">
+                    You are offline, the data may be outdated
+                </Alert>
+            </IsOffline>
+            <SimpleList primaryText="%{title}" secondaryText="%{author}" />
+        </>
+    );
+};
+
+const CustomOffline = () => {
+    return <Alert severity="warning">You are offline!</Alert>;
+};
+
+Offline.args = {
+    isOnline: true,
+    offline: 'default',
+    pagination: 'infinite',
+};
+
+Offline.argTypes = {
+    isOnline: {
+        control: { type: 'boolean' },
+    },
+    pagination: {
+        control: { type: 'radio' },
+        options: ['infinite', 'classic'],
+        mapping: {
+            infinite: <InfinitePagination />,
+            classic: <DefaultPagination />,
+        },
+    },
+    offline: {
+        name: 'Offline component',
+        control: { type: 'radio' },
+        options: ['default', 'custom'],
+        mapping: {
+            default: undefined,
+            custom: <CustomOffline />,
+        },
+    },
+};
diff --git a/packages/ra-ui-materialui/src/list/InfiniteList.tsx b/packages/ra-ui-materialui/src/list/InfiniteList.tsx
@@ -103,6 +103,8 @@ export const InfiniteList = <RecordType extends RaRecord = any>(
             resource={resource}
             sort={sort}
             storeKey={storeKey}
+            // Disable offline support from InfiniteListBase as it is handled by ListView to keep the ListView container
+            offline={false}
         >
             <ListView<RecordType> {...rest} pagination={pagination} />
         </InfiniteListBase>
diff --git a/packages/ra-ui-materialui/src/list/List.tsx b/packages/ra-ui-materialui/src/list/List.tsx
@@ -100,7 +100,7 @@ export const List = <RecordType extends RaRecord = any>(
             resource={resource}
             sort={sort}
             storeKey={storeKey}
-            // Disable offline support from ShowBase as it is handled by ShowView to keep the ShowView container
+            // Disable offline support from ListBase as it is handled by ListView to keep the ListView container
             offline={false}
         >
             <ListView<RecordType> {...rest} render={render} />
diff --git a/packages/ra-ui-materialui/src/list/ListView.tsx b/packages/ra-ui-materialui/src/list/ListView.tsx
@@ -356,7 +356,7 @@ export interface ListViewProps<RecordType extends RaRecord = any> {
      *     </List>
      * );
      */
-    pagination?: ReactElement | false;
+    pagination?: ReactNode | false;
 
     /**
      * The page title (main title) to display above the data. Defaults to the humanized resource name.
diff --git a/packages/ra-ui-materialui/src/list/pagination/InfinitePagination.tsx b/packages/ra-ui-materialui/src/list/pagination/InfinitePagination.tsx

Original file line number	Diff line number	Diff line change
`@@ -103,6 +103,8 @@ export const InfiniteList = <RecordType extends RaRecord = any>(`
`103`	`103`	`resource={resource}`
`104`	`104`	`sort={sort}`
`105`	`105`	`storeKey={storeKey}`
	`106`	`+ // Disable offline support from InfiniteListBase as it is handled by ListView to keep the ListView container`
	`107`	`+ offline={false}`
`106`	`108`	`>`
`107`	`109`	`<ListView<RecordType> {...rest} pagination={pagination} />`
`108`	`110`	`</InfiniteListBase>`
Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ export const List = <RecordType extends RaRecord = any>(`
`100`	`100`	`resource={resource}`
`101`	`101`	`sort={sort}`
`102`	`102`	`storeKey={storeKey}`
`103`		`- // Disable offline support from ShowBase as it is handled by ShowView to keep the ShowView container`
	`103`	`+ // Disable offline support from ListBase as it is handled by ListView to keep the ListView container`
`104`	`104`	`offline={false}`
`105`	`105`	`>`
`106`	`106`	`<ListView<RecordType> {...rest} render={render} />`