add render prop on ReferenceField

Author: ThieryMichel

docs/ReferenceField.md

@@ -75,6 +75,7 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
 | `source`    | Required | `string`            | -        | Name of the property to display |
 | `reference` | Required | `string`            | -        | The name of the resource for the referenced records, e.g. 'posts' |
 | `children`  | Optional | `ReactNode`         | -        | One or more Field elements used to render the referenced record |
+| `render`  | Optional | (referenceFieldContext) => `ReactNode`         | -        | A function used to render the referenced record, receive the reference field context as its argument |
 | `empty`     | Optional | `ReactNode`         | -        | What to render when the field has no value or when the reference is missing |
 | `label`     | Optional | `string | Function` | `resources. [resource]. fields.[source]`   | Label to use for the field when rendered in layout components  |
 | `link`      | Optional | `string | Function` | `edit`   | Target of the link wrapping the rendered child. Set to `false` to disable the link. |
@@ -83,6 +84,29 @@ It uses `dataProvider.getMany()` instead of `dataProvider.getOne()` [for perform
 
 `<ReferenceField>` also accepts the [common field props](./Fields.md#common-field-props).
 
+## `render`
+
+Alternatively you can pass a render prop instead of children to be able to inline the rendering. The render function will then receive the reference field context directly.
+
+```jsx
+export const MyReferenceField = () => (
+    <ReferenceField source="user_id" reference="users"  render={({ error, isPending, referenceRecord }) => {
+        if (isPending) {
+            return <p>Loading...</p>;
+        }
+
+        if (error) {
+            return (
+                <p className="error">
+                    {error.message}
+                </p>
+            );
+        }
+        return <p>{referenceRecord.name}</p>;
+    }} />
+);
+```
+
 ## `empty`
 
 `<ReferenceField>` can display a custom message when the referenced record is missing, thanks to the `empty` prop.

docs/ReferenceFieldBase.md

@@ -118,7 +118,7 @@ export const MyReferenceField = () => (
     <ReferenceFieldBase
         source="user_id"
         reference="users"
-        render={({ error, isPending }) => {
+        render={({ error, isPending, referenceRecord }) => {
             if (isPending) {
                 return <p>Loading...</p>;
             }
@@ -130,7 +130,7 @@ export const MyReferenceField = () => (
                     </p>
                 );
             }
-            return <p>{value}</p>;
+            return <p>{referenceRecord.name}</p>;
         }}
     />
 );

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

@@ -506,6 +506,46 @@ describe('<ReferenceField />', () => {
         await screen.findByText('boo');
     });
 
+    it('should render its child using render prop when given', async () => {
+        const dataProvider = testDataProvider({
+            getMany: jest.fn().mockResolvedValue({
+                data: [{ id: 123, title: 'foo' }],
+            }),
+        });
+        render(
+            <ThemeProvider theme={theme}>
+                <CoreAdminContext dataProvider={dataProvider}>
+                    <ResourceDefinitionContextProvider
+                        definitions={{
+                            posts: {
+                                name: 'posts',
+                                hasEdit: true,
+                            },
+                        }}
+                    >
+                        <RecordContextProvider value={record}>
+                            <ReferenceField
+                                resource="comments"
+                                source="postId"
+                                reference="posts"
+                                render={({ referenceRecord }) =>
+                                    referenceRecord?.title || 'No title'
+                                }
+                            />
+                        </RecordContextProvider>
+                    </ResourceDefinitionContextProvider>
+                </CoreAdminContext>
+            </ThemeProvider>
+        );
+        await new Promise(resolve => setTimeout(resolve, 10));
+        expect(screen.queryByRole('progressbar')).toBeNull();
+        expect(screen.getByText('foo')).not.toBeNull();
+        expect(screen.queryAllByRole('link')).toHaveLength(1);
+        expect(screen.queryByRole('link')?.getAttribute('href')).toBe(
+            '#/posts/123'
+        );
+    });
+
     describe('link', () => {
         it('should render a link to specified link type', async () => {
             render(<LinkShow />);

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

@@ -951,3 +951,23 @@ export const Themed = () => {
         </Wrapper>
     );
 };
+
+export const WithRenderProp = () => (
+    <Wrapper>
+        <ReferenceField
+            source="detail_id"
+            reference="book_details"
+            render={({ error, isPending, referenceRecord }) => {
+                console.log({ error, isPending, referenceRecord });
+                if (isPending) {
+                    return <p>Loading...</p>;
+                }
+
+                if (error) {
+                    return <p style={{ color: 'red' }}>{error.message}</p>;
+                }
+                return referenceRecord.ISBN;
+            }}
+        ></ReferenceField>
+    </Wrapper>
+);

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

@@ -16,6 +16,7 @@ import {
     type RaRecord,
     ReferenceFieldBase,
     useReferenceFieldContext,
+    UseReferenceFieldControllerResult,
 } from 'ra-core';
 import type { UseQueryOptions } from '@tanstack/react-query';
 import clsx from 'clsx';
@@ -40,6 +41,14 @@ import { visuallyHidden } from '@mui/utils';
  *     <TextField source="name" />
  * </ReferenceField>
  *
+ * @example // using a render prop to render the record
+ * <ReferenceField label="User" source="userId" reference="users" render={
+ *     (context) => (
+ *         <p>{context.referenceRecord?.name}</p>
+ *     )
+ * }>
+ * </ReferenceField>
+ *
  * @example // By default, includes a link to the <Edit> page of the related record
  * // (`/users/:userId` in the previous example).
  * // Set the `link` prop to "show" to link to the <Show> page instead.
@@ -60,9 +69,11 @@ import { visuallyHidden } from '@mui/utils';
 export const ReferenceField = <
     RecordType extends Record<string, any> = Record<string, any>,
     ReferenceRecordType extends RaRecord = RaRecord,
->(
-    inProps: ReferenceFieldProps<RecordType, ReferenceRecordType>
-) => {
+>({
+    children,
+    render,
+    ...inProps
+}: ReferenceFieldProps<RecordType, ReferenceRecordType>) => {
     const props = useThemeProps({
         props: inProps,
         name: PREFIX,
@@ -89,6 +100,8 @@ export const ReferenceField = <
         >
             <PureReferenceFieldView<RecordType, ReferenceRecordType>
                 {...props}
+                render={render}
+                children={children}
             />
         </ReferenceFieldBase>
     );
@@ -99,6 +112,9 @@ export interface ReferenceFieldProps<
     ReferenceRecordType extends RaRecord = RaRecord,
 > extends FieldProps<RecordType> {
     children?: ReactNode;
+    render?: (
+        context: UseReferenceFieldControllerResult<ReferenceRecordType>
+    ) => ReactNode;
     /**
      * @deprecated Use the empty prop instead
      */
@@ -123,13 +139,13 @@ export const ReferenceFieldView = <
 >(
     props: ReferenceFieldViewProps<RecordType, ReferenceRecordType>
 ) => {
-    const { children, className, emptyText, reference, sx, ...rest } =
+    const { children, render, className, emptyText, reference, sx, ...rest } =
         useThemeProps({
             props: props,
             name: PREFIX,
         });
-    const { error, link, isLoading, referenceRecord } =
-        useReferenceFieldContext();
+    const referenceFieldContext = useReferenceFieldContext();
+    const { error, link, isLoading, referenceRecord } = referenceFieldContext;
 
     const getRecordRepresentation = useGetRecordRepresentation(reference);
 
@@ -150,7 +166,7 @@ export const ReferenceFieldView = <
         return <LinearProgress />;
     }
 
-    const child = children || (
+    const child = (render ? render(referenceFieldContext) : children) || (
         <Typography component="span" variant="body2">
             {getRecordRepresentation(referenceRecord)}
         </Typography>
@@ -192,6 +208,9 @@ export interface ReferenceFieldViewProps<
 > extends FieldProps<RecordType>,
         Omit<ReferenceFieldProps<RecordType, ReferenceRecordType>, 'link'> {
     children?: ReactNode;
+    render?: (
+        context: UseReferenceFieldControllerResult<RaRecord>
+    ) => ReactNode;
     reference: string;
     resource?: string;
     translateChoice?: Function | boolean;