Merge pull request #11104 from marmelab/fix-docs-validate-prop

[Doc] Clarify validation prop usage on ReferenceInput/ReferenceArrayInput

Author: fzaninotto

docs/AutocompleteArrayInput.md

@@ -126,6 +126,8 @@ If you need to *fetch* the options from another resource, you're actually editin
 </ReferenceArrayInput>
 ```
 
+**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child `<AutocompleteArrayInput>`. `<ReferenceArrayInput>` doesn't accept validation props.
+
 You can also pass an *array of strings* for the choices:
 
 ```jsx
@@ -839,4 +841,3 @@ const CreateTag = () => {
 };
 ```
 {% endraw %}
-

docs/AutocompleteInput.md

@@ -764,19 +764,22 @@ const CompanyInput = () => {
 As this is a common task, react-admin provides a shortcut to do the same in a declarative way: [`<ReferenceInput>`](./ReferenceInput.md):
 
 ```jsx
-import { ReferenceInput, AutocompleteInput } from 'react-admin';
+import { ReferenceInput, AutocompleteInput, required } from 'react-admin';
 
 const CompanyInput = () => (
     <ReferenceInput reference="companies" source="company_id">
         <AutocompleteInput 
             label="Company"
             source="company_id"
             optionText="name"
+            validate={required()}
         />
     </ReferenceInput>
 );
 ```
 
+**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child input (`<AutocompleteInput>`). `<ReferenceInput>` doesn't accept validation props.
+
 `<ReferenceInput>` is a headless component that:
 
  - fetches a list of records with `dataProvider.getList()` and `dataProvider.getOne()`, using the `reference` prop for the resource,

docs/DualListInput.md

@@ -134,6 +134,8 @@ If you need to *fetch* the options from another resource, you're actually editin
 </ReferenceArrayInput>
 ```
 
+**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child `<DualListInput>`. `<ReferenceArrayInput>` doesn't accept validation props.
+
 If you have an *array of values* for the options, turn it into an array of objects with the `id` and `name` properties:
 
 ```jsx

docs/RadioButtonGroupInput.md

@@ -386,19 +386,22 @@ const CompanyInput = () => {
 As this is a common task, react-admin provides a shortcut to do the same in a declarative way: [`<ReferenceInput>`](./ReferenceInput.md):
 
 ```jsx
-import { ReferenceInput, RadioButtonGroupInput } from 'react-admin';
+import { ReferenceInput, RadioButtonGroupInput, required } from 'react-admin';
 
 const CompanyInput = () => (
     <ReferenceInput reference="companies" source="company_id">
         <RadioButtonGroupInput 
             label="Company"
             source="company_id"
             optionText="name"
+            validate={required()}
         />
     </ReferenceInput>
 );
 ```
 
+**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child `<RadioButtonGroupInput>`. `<ReferenceInput>` doesn't accept validation props.
+
 `<ReferenceInput>` is a headless component that:
 
  - fetches a list of records with `dataProvider.getList()` and `dataProvider.getOne()`, using the `reference` prop for the resource,

docs/ReferenceArrayInput.md

@@ -111,7 +111,19 @@ See the [`children`](#children) section for more details.
 | `queryOptions`     | Optional | [`UseQueryOptions`](https://tanstack.com/query/v5/docs/react/reference/useQuery) | `{}` | `react-query` client options     |
 | `sort`             | Optional | `{ field: String, order: 'ASC' or 'DESC' }` | `{ field: 'id', order: 'DESC' }`   | How to order the list of suggestions                                                                                |
 
-**Note**: `<ReferenceArrayInput>` doesn't accept the [common input props](./Inputs.md#common-input-props) ; it is the responsability of children to apply them.
+**Note**: `<ReferenceArrayInput>` doesn't accept the [common input props](./Inputs.md#common-input-props) ; it is the responsability of children to apply them. The same is true for validation: put the `validate` prop on the child input (`<AutocompleteArrayInput>`, `<SelectArrayInput>`, `<DualListInput>`, etc.), not on `<ReferenceArrayInput>`.
+
+## Validation
+
+`<ReferenceArrayInput>` doesn't accept a `validate` prop. Put validation on the child input instead (`<AutocompleteArrayInput>`, `<SelectArrayInput>`, `<DualListInput>`, etc.).
+
+```jsx
+import { ReferenceArrayInput, SelectArrayInput, required } from 'react-admin';
+
+<ReferenceArrayInput source="tag_ids" reference="tags">
+    <SelectArrayInput validate={required()} />
+</ReferenceArrayInput>
+```
 
 ## `children`
 

docs/ReferenceInput.md

@@ -114,7 +114,19 @@ See the [`children`](#children) section for more details.
 | `queryOptions`     | Optional | [`UseQueryOptions`](https://tanstack.com/query/v5/docs/react/reference/useQuery)                       | `{}`                             | `react-query` client options                                                                   |
 | `sort`             | Optional | `{ field: String, order: 'ASC' or 'DESC' }` | `{ field:'id', order:'DESC' }` | How to order the list of suggestions                                                           |
 
-**Note**: `<ReferenceInput>` doesn't accept the [common input props](./Inputs.md#common-input-props) (like `label`) ; it is the responsibility of the child component to apply them.
+**Note**: `<ReferenceInput>` doesn't accept the [common input props](./Inputs.md#common-input-props) (like `label`) ; it is the responsibility of the child component to apply them. The same goes for validation: pass `validate` to the child input (`<AutocompleteInput>`, `<SelectInput>`, `<RadioButtonGroupInput>`, etc.), not to `<ReferenceInput>`. This also applies to other reference inputs like [`<ReferenceArrayInput>`](./ReferenceArrayInput.md).
+
+## Validation
+
+`<ReferenceInput>` doesn't accept a `validate` prop. Put validation on the child input instead (`<AutocompleteInput>`, `<SelectInput>`, `<RadioButtonGroupInput>`, etc.).
+
+```jsx
+import { ReferenceInput, SelectInput, required } from 'react-admin';
+
+<ReferenceInput source="company_id" reference="companies">
+    <SelectInput validate={required()} />
+</ReferenceInput>
+```
 
 ## `children`
 

docs/SelectArrayInput.md

@@ -132,6 +132,8 @@ If you need to *fetch* the options from another resource, you're actually editin
 </ReferenceArrayInput>
 ```
 
+**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child `<SelectArrayInput>`. `<ReferenceArrayInput>` doesn't accept validation props.
+
 You can also pass an *array of strings* for the choices:
 
 ```jsx

docs/SelectInput.md

@@ -594,19 +594,22 @@ const CompanyInput = () => {
 As this is a common task, react-admin provides a shortcut to do the same in a declarative way: [`<ReferenceInput>`](./ReferenceInput.md):
 
 ```jsx
-import { ReferenceInput, SelectInput } from 'react-admin';
+import { ReferenceInput, SelectInput, required } from 'react-admin';
 
 const CompanyInput = () => (
     <ReferenceInput reference="companies" source="company_id">
         <SelectInput
             label="Company"
             source="company_id"
             optionText="name"
+            validate={required()}
         />
     </ReferenceInput>
 );
 ```
 
+**Tip**: When the input needs validation (e.g. `required()`), add the `validate` prop to the child `<SelectInput>`. `<ReferenceInput>` doesn't accept validation props.
+
 `<ReferenceInput>` is a headless component that:
 
  - fetches a list of records with `dataProvider.getList()` and `dataProvider.getOne()`, using the `reference` prop for the resource,