Add <ReferenceField empty> prop

Author: fzaninotto

docs/ReferenceField.md

@@ -74,26 +74,38 @@ 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 |
-| `emptyText` | Optional | `string`            | ''       | Defines a text to be shown when the field has no value or when the reference is missing |
+| `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. |
 | `queryOptions`     | Optional | [`UseQuery Options`](https://tanstack.com/query/v5/docs/react/reference/useQuery)                       | `{}`                             | `react-query` client options                                                                   |
 | `sortBy`    | Optional | `string | Function` | `source` | Name of the field to use for sorting when used in a Datagrid |
 
 `<ReferenceField>` also accepts the [common field props](./Fields.md#common-field-props).
 
-## `emptyText`
+## `empty`
 
-`<ReferenceField>` can display a custom message when the referenced record is missing, thanks to the `emptyText` prop.
+`<ReferenceField>` can display a custom message when the referenced record is missing, thanks to the `empty` prop.
 
 ```jsx
-<ReferenceField source="user_id" reference="users" emptyText="Missing user" />
+<ReferenceField source="user_id" reference="users" empty="Missing user" />
 ```
 
-`<ReferenceField>` renders the `emptyText`:
+`<ReferenceField>` renders the `empty` element when:
 
-- when the referenced record is missing (no record in the `users` table with the right `user_id`), or
-- when the field is empty (no `user_id` in the record).
+- the referenced record is missing (no record in the `users` table with the right `user_id`), or
+- the field is empty (no `user_id` in the record).
+
+When `empty` is a string, `<ReferenceField>` renders it as a `<Typography>` and passes the text through the i18n system, so you can use translation keys to have one message for each language supported by the interface:
+
+```jsx
+<ReferenceField source="user_id" reference="users" empty="resources.users.missing" />
+```
+
+You can also pass a React element to the `empty` prop:
+
+```jsx
+<ReferenceField source="user_id" reference="users" empty={<span>Missing user</span>} />
+```
 
 ## `label`
 

docs/WithRecord.md

@@ -23,7 +23,7 @@ const BookShow = () => (
 );
 ```
 
-Note that if `record` is undefined, `<WithRecord>` doesn't call the `render` callback and renders nothing, so you don't have to worry about this case in your render callback.
+Note that if `record` is undefined, `<WithRecord>` doesn't call the `render` callback and renders nothing (or the `empty` prop), so you don't have to worry about this case in your render callback.
 
 ## Availability
 

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

@@ -158,6 +158,32 @@ export const MissingReferenceIdEmptyTextTranslation = () => (
     </Wrapper>
 );
 
+export const MissingReferenceIdEmpty = () => (
+    <Wrapper record={{ id: 1, title: 'War and Peace' }}>
+        <ReferenceField
+            source="detail_id"
+            reference="book_details"
+            empty={<b>no detail</b>}
+        >
+            <TextField source="ISBN" />
+        </ReferenceField>
+    </Wrapper>
+);
+
+export const MissingReferenceIdEmptyTranslation = () => (
+    <Wrapper record={{ id: 1, title: 'War and Peace' }}>
+        <I18nContextProvider value={i18nProvider}>
+            <ReferenceField
+                source="detail_id"
+                reference="book_details"
+                empty="resources.books.not_found"
+            >
+                <TextField source="ISBN" />
+            </ReferenceField>
+        </I18nContextProvider>
+    </Wrapper>
+);
+
 const missingReferenceDataProvider = {
     getMany: () =>
         Promise.resolve({

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

@@ -68,20 +68,26 @@ export const ReferenceField = <
         props: inProps,
         name: PREFIX,
     });
-    const { emptyText } = props;
+    const { emptyText, empty } = props;
     const translate = useTranslate();
-    const id = useFieldValue(props);
-
-    if (id == null) {
-        return emptyText ? (
-            <Typography component="span" variant="body2">
-                {emptyText && translate(emptyText, { _: emptyText })}
-            </Typography>
-        ) : null;
-    }
 
     return (
-        <ReferenceFieldBase<ReferenceRecordType> {...props}>
+        <ReferenceFieldBase<ReferenceRecordType>
+            {...props}
+            empty={
+                emptyText ? (
+                    <Typography component="span" variant="body2">
+                        {emptyText && translate(emptyText, { _: emptyText })}
+                    </Typography>
+                ) : typeof empty === 'string' ? (
+                    <Typography component="span" variant="body2">
+                        {empty && translate(empty, { _: empty })}
+                    </Typography>
+                ) : (
+                    empty ?? null
+                )
+            }
+        >
             <PureReferenceFieldView<RecordType, ReferenceRecordType>
                 {...props}
             />
@@ -94,6 +100,11 @@ export interface ReferenceFieldProps<
     ReferenceRecordType extends RaRecord = RaRecord,
 > extends FieldProps<RecordType> {
     children?: ReactNode;
+    /**
+     * @deprecated Use the empty prop instead
+     */
+    emptyText?: string;
+    empty?: ReactNode;
     queryOptions?: Omit<
         UseQueryOptions<ReferenceRecordType[], Error>,
         'queryFn' | 'queryKey'
@@ -122,7 +133,6 @@ export const ReferenceFieldView = <
         useReferenceFieldContext();
 
     const getRecordRepresentation = useGetRecordRepresentation(reference);
-    const translate = useTranslate();
 
     if (error) {
         return (
@@ -140,13 +150,6 @@ export const ReferenceFieldView = <
     if (isLoading) {
         return <LinearProgress />;
     }
-    if (!referenceRecord) {
-        return emptyText ? (
-            <Typography component="span" variant="body2">
-                {emptyText && translate(emptyText, { _: emptyText })}
-            </Typography>
-        ) : null;
-    }
 
     const child = children || (
         <Typography component="span" variant="body2">