Merge pull request marmelab#10940 from marmelab/empty-list-base

slax57 · web-flow · commit cf71dae258bc · 2025-11-05T17:23:42.000+01:00
Add empty property to ListBase and InfiniteListBase
diff --git a/docs/ListBase.md b/docs/ListBase.md
@@ -85,6 +85,7 @@ The `<ListBase>` component accepts the following props:
 * [`debounce`](./List.md#debounce)
 * [`disableAuthentication`](./List.md#disableauthentication)
 * [`disableSyncWithLocation`](./List.md#disablesyncwithlocation)
+* [`empty`](./List.md#empty)
 * [`emptyWhileLoading`](./List.md#emptywhileloading)
 * [`error`](./List.md#error)
 * [`exporter`](./List.md#exporter)
diff --git a/docs_headless/src/content/docs/InfiniteListBase.md b/docs_headless/src/content/docs/InfiniteListBase.md
@@ -106,6 +106,8 @@ That's enough to display a basic list with infinite scroll functionality. When u
 | `debounce`                 | Optional                | `number`    | `500`   | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
 | `disable Authentication`   | Optional                | `boolean`   | `false` | Set to `true` to disable the authentication check.                                           |
 | `disable SyncWithLocation` | Optional                | `boolean`   | `false` | Set to `true` to disable the synchronization of the list parameters with the URL.            |
+| `empty`                    | Optional                | `ReactNode` | -       | The component to display when the list is empty.                                             |
+| `emptyWhileLoading`        | Optional                | `boolean`   | -       | Set to `true` to return `null` while the list is loading.                                    |
 | `error`                    | Optional                | `ReactNode` | -       | The component to render when failing to load the list of records.                            |
 | `exporter`                 | Optional                | `function`  | -       | The function to call to export the list.                                                     |
 | `filter`                   | Optional                | `object`    | -       | The permanent filter values.                                                                 |
diff --git a/docs_headless/src/content/docs/ListBase.md b/docs_headless/src/content/docs/ListBase.md
@@ -86,6 +86,8 @@ The `<ListBase>` component accepts the following props:
 | `debounce`                | Optional                | `number`    | `500`   | The debounce delay in milliseconds to apply when users change the sort or filter parameters. |
 | `disableAuthentication`   | Optional                | `boolean`   | `false` | Set to `true` to disable the authentication check.                                           |
 | `disableSyncWithLocation` | Optional                | `boolean`   | `false` | Set to `true` to disable the synchronization of the list parameters with the URL.            |
+| `empty`                   | Optional                | `ReactNode` | -       | The component to display when the list is empty.                                             |
+| `emptyWhileLoading`       | Optional                | `boolean`   | -       | Set to `true` to return `null` while the list is loading.                                    |
 | `error`                   | Optional                | `ReactNode` | -       | The component to render when failing to load the list of records.                            |
 | `exporter`                | Optional                | `function`  | -       | The function to call to export the list.                                                     |
 | `filter`                  | Optional                | `object`    | -       | The permanent filter values.                                                                 |
@@ -210,6 +212,90 @@ const Dashboard = () => (
 );
 ```
 
+## `empty`
+
+By default, `<ListBase>` renders the children when there is no result and no active filter. If you want for instance to invite users to create the first record, you can render a custom component via the `empty` prop:
+
+```jsx
+import { ListBase } from 'ra-core';
+import { Link } from 'react-router';
+
+const Empty = () => (
+    <div>
+        <h4>
+            No product available
+        </h4>
+        <Link to="/products/create">Create the first product</Link>
+    </div>
+);
+
+const ProductList = () => (
+    <ListBase empty={<Empty />}>
+        ...
+    </ListBase>
+);
+```
+
+The `empty` component can call the [`useListContext()`](./useListContext.md) hook to receive the same props as the `ListBase` child component.
+
+## `emptyWhileLoading`
+
+Many list view components return null when the data is loading. If you use a custom view component as the `<ListBase>` children instead, you'll have to handle the case where the `data` is not yet defined.
+
+That means that the following will fail on load with a "ReferenceError: data is not defined" error:
+
+```jsx
+import { ListBase, useListContext } from 'ra-core';
+
+const SimpleBookList = () => {
+    const { data } = useListContext();
+    return (
+        <ul>
+            {data.map(book => (
+                <li key={book.id}>
+                    <i>{book.title}</i>, by {book.author} ({book.year})
+                </li>
+            ))}
+        </ul>
+    );
+}
+
+const BookList = () => (
+    <ListBase>
+        <SimpleBookList />
+    </ListBase>
+);
+```
+
+You can handle this case by getting the `isPending` variable from the [`useListContext`](./useListContext.md) hook:
+
+```jsx
+const SimpleBookList = () => {
+    const { data, isPending } = useListContext();
+    if (isPending) return null;
+    return (
+        <ul>
+            {data.map(book => (
+                <li key={book.id}>
+                    <i>{book.title}</i>, by {book.author} ({book.year})
+                </li>
+            ))}
+        </ul>
+    );
+}
+```
+
+The `<ListBase emptyWhileLoading>` prop provides a convenient shortcut for that use case. When enabled, `<ListBase>` won't render its child until `data` is defined.
+
+```diff
+const BookList = () => (
+-   <ListBase>
++   <ListBase emptyWhileLoading>
+        <SimpleBookList />
+    </ListBase>
+);
+```
+
 ## `error`
 
 By default, `<ListBase>` renders the children when an error happens while loading the list of records. You can render an error component via the `error` prop:
diff --git a/packages/ra-core/src/controller/list/InfiniteListBase.spec.tsx b/packages/ra-core/src/controller/list/InfiniteListBase.spec.tsx
@@ -3,6 +3,7 @@ import {
     AccessControl,
     Basic,
     DefaultTitle,
+    Empty,
     FetchError,
     Loading,
     NoAuthProvider,
@@ -160,6 +161,14 @@ describe('InfiniteListBase', () => {
         expect(screen.queryByText('Loading...')).toBeNull();
     });
 
+    it('should render a custom empty component when data is empty', async () => {
+        render(<Empty />);
+        expect(screen.queryByText('Loading...')).not.toBeNull();
+        expect(screen.queryByText('War and Peace')).toBeNull();
+        fireEvent.click(screen.getByText('Resolve books loading'));
+        await screen.findByText('No books');
+    });
+
     it('should render loading component while loading', async () => {
         render(<Loading />);
         expect(screen.queryByText('Loading books...')).not.toBeNull();
diff --git a/packages/ra-core/src/controller/list/InfiniteListBase.stories.tsx b/packages/ra-core/src/controller/list/InfiniteListBase.stories.tsx
@@ -252,6 +252,39 @@ export const FetchError = () => {
     );
 };
 
+export const Empty = () => {
+    let resolveGetList: (() => void) | null = null;
+    const dataProvider = {
+        ...defaultDataProvider,
+        getList: () => {
+            return new Promise<GetListResult>(resolve => {
+                resolveGetList = () => resolve({ data: [], total: 0 });
+            });
+        },
+    };
+
+    return (
+        <CoreAdminContext dataProvider={dataProvider}>
+            <button
+                onClick={() => {
+                    resolveGetList && resolveGetList();
+                }}
+            >
+                Resolve books loading
+            </button>
+            <InfiniteListBase
+                resource="books"
+                perPage={5}
+                loading={<p>Loading...</p>}
+                empty={<p>No books</p>}
+            >
+                <BookListView />
+                <InfinitePagination />
+            </InfiniteListBase>
+        </CoreAdminContext>
+    );
+};
+
 const defaultI18nProvider = polyglotI18nProvider(
     locale =>
         locale === 'fr'
diff --git a/packages/ra-core/src/controller/list/InfiniteListBase.tsx b/packages/ra-core/src/controller/list/InfiniteListBase.tsx
@@ -50,6 +50,7 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
     loading,
     offline,
     error,
+    empty,
     children,
     render,
     ...props
@@ -71,6 +72,11 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
         isPending,
         isPlaceholderData,
         error: errorState,
+        data,
+        total,
+        hasPreviousPage,
+        hasNextPage,
+        filterValues,
     } = controllerProps;
 
     const showAuthLoading =
@@ -95,6 +101,23 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
 
     const showError = errorState && error !== false && error !== undefined;
 
+    const showEmpty =
+        !errorState &&
+        // the list is not loading data for the first time
+        !isPending &&
+        // the API returned no data (using either normal or partial pagination)
+        (total === 0 ||
+            (total == null &&
+                hasPreviousPage === false &&
+                hasNextPage === false &&
+                // @ts-ignore FIXME total may be undefined when using partial pagination but the ListControllerResult type is wrong about it
+                data.length === 0)) &&
+        // the user didn't set any filters
+        !Object.keys(filterValues).length &&
+        // there is an empty page component
+        empty !== undefined &&
+        empty !== 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}>
@@ -118,9 +141,11 @@ export const InfiniteListBase = <RecordType extends RaRecord = any>({
                             ? offline
                             : showError
                               ? error
-                              : render
-                                ? render(controllerProps)
-                                : children}
+                              : showEmpty
+                                ? empty
+                                : render
+                                  ? render(controllerProps)
+                                  : children}
                 </InfinitePaginationContext.Provider>
             </ListContextProvider>
         </OptionalResourceContextProvider>
@@ -133,6 +158,7 @@ export interface InfiniteListBaseProps<RecordType extends RaRecord = any>
     loading?: ReactNode;
     offline?: ReactNode;
     error?: ReactNode;
+    empty?: ReactNode;
     children?: ReactNode;
     render?: (props: InfiniteListControllerResult<RecordType>) => ReactNode;
 }
diff --git a/packages/ra-core/src/controller/list/ListBase.spec.tsx b/packages/ra-core/src/controller/list/ListBase.spec.tsx
@@ -3,6 +3,7 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import {
     AccessControl,
     DefaultTitle,
+    Empty,
     EmptyWhileLoading,
     EmptyWhileLoadingRender,
     FetchError,
@@ -168,6 +169,13 @@ describe('ListBase', () => {
         await screen.findByText('War and Peace');
         await screen.findByText('You are offline, the data may be outdated');
     });
+    it('should render a custom empty component when data is empty', async () => {
+        render(<Empty />);
+        expect(screen.queryByText('Loading...')).not.toBeNull();
+        expect(screen.queryByText('War and Peace')).toBeNull();
+        fireEvent.click(screen.getByText('Resolve books loading'));
+        await screen.findByText('No books');
+    });
     it('should render nothing while loading if emptyWhileLoading is set to true', async () => {
         render(<EmptyWhileLoading />);
         expect(screen.queryByText('Loading...')).toBeNull();
diff --git a/packages/ra-core/src/controller/list/ListBase.stories.tsx b/packages/ra-core/src/controller/list/ListBase.stories.tsx
@@ -503,6 +503,39 @@ export const FetchError = () => {
     );
 };
 
+export const Empty = () => {
+    let resolveGetList: (() => void) | null = null;
+    const baseProvider = defaultDataProvider(0);
+    const dataProvider = {
+        ...baseProvider,
+        getList: () => {
+            return new Promise<GetListResult>(resolve => {
+                resolveGetList = () => resolve({ data: [], total: 0 });
+            });
+        },
+    };
+
+    return (
+        <CoreAdminContext dataProvider={dataProvider}>
+            <button
+                onClick={() => {
+                    resolveGetList && resolveGetList();
+                }}
+            >
+                Resolve books loading
+            </button>
+            <ListBase
+                resource="books"
+                perPage={5}
+                loading={<p>Loading...</p>}
+                empty={<p>No books</p>}
+            >
+                <BookListView />
+            </ListBase>
+        </CoreAdminContext>
+    );
+};
+
 export const EmptyWhileLoading = () => {
     let resolveGetList: (() => void) | null = null;
     const baseProvider = defaultDataProvider(0);
diff --git a/packages/ra-core/src/controller/list/ListBase.tsx b/packages/ra-core/src/controller/list/ListBase.tsx
@@ -51,6 +51,7 @@ export const ListBase = <RecordType extends RaRecord = any>({
     loading,
     offline,
     error,
+    empty,
     render,
     ...props
 }: ListBaseProps<RecordType>) => {
@@ -71,6 +72,11 @@ export const ListBase = <RecordType extends RaRecord = any>({
         isPending,
         isPlaceholderData,
         error: errorState,
+        data,
+        total,
+        hasPreviousPage,
+        hasNextPage,
+        filterValues,
     } = controllerProps;
 
     const showAuthLoading =
@@ -95,7 +101,25 @@ export const ListBase = <RecordType extends RaRecord = any>({
 
     const showError = errorState && error !== false && error !== undefined;
 
-    const showEmpty = isPending && !showOffline && emptyWhileLoading === true;
+    const showEmptyWhileLoading =
+        isPending && !showOffline && emptyWhileLoading === true;
+
+    const showEmpty =
+        !errorState &&
+        // the list is not loading data for the first time
+        !isPending &&
+        // the API returned no data (using either normal or partial pagination)
+        (total === 0 ||
+            (total == null &&
+                hasPreviousPage === false &&
+                hasNextPage === false &&
+                // @ts-ignore FIXME total may be undefined when using partial pagination but the ListControllerResult type is wrong about it
+                data.length === 0)) &&
+        // the user didn't set any filters
+        !Object.keys(filterValues).length &&
+        // there is an empty page component
+        empty !== undefined &&
+        empty !== false;
 
     return (
         // We pass props.resource here as we don't need to create a new ResourceContext if the props is not provided
@@ -109,11 +133,13 @@ export const ListBase = <RecordType extends RaRecord = any>({
                         ? offline
                         : showError
                           ? error
-                          : showEmpty
+                          : showEmptyWhileLoading
                             ? null
-                            : render
-                              ? render(controllerProps)
-                              : children}
+                            : showEmpty
+                              ? empty
+                              : render
+                                ? render(controllerProps)
+                                : children}
             </ListContextProvider>
         </OptionalResourceContextProvider>
     );
@@ -126,6 +152,7 @@ export interface ListBaseProps<RecordType extends RaRecord = any>
     loading?: ReactNode;
     offline?: ReactNode;
     error?: ReactNode;
+    empty?: ReactNode;
     children?: ReactNode;
     render?: (props: ListControllerResult<RecordType, Error>) => ReactNode;
 }
diff --git a/packages/ra-ui-materialui/src/list/InfiniteList.tsx b/packages/ra-ui-materialui/src/list/InfiniteList.tsx
@@ -117,7 +117,10 @@ const defaultFilter = {};
 const defaultAuthLoading = <Loading />;
 
 export interface InfiniteListProps<RecordType extends RaRecord = any>
-    extends Omit<InfiniteListBaseProps<RecordType>, 'children' | 'render'>,
+    extends Omit<
+            InfiniteListBaseProps<RecordType>,
+            'children' | 'render' | 'empty'
+        >,
         ListViewProps {}
 
 const PREFIX = 'RaInfiniteList';
diff --git a/packages/ra-ui-materialui/src/list/List.tsx b/packages/ra-ui-materialui/src/list/List.tsx
