You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/AutocompleteInput.md
+31-18Lines changed: 31 additions & 18 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -15,7 +15,7 @@ It renders using [Material UI's `<Autocomplete>`](https://mui.com/material-ui/re
15
15
Your browser does not support the video tag.
16
16
</video>
17
17
18
-
This input allows editing record fields that are scalar values, e.g. `123`, `'admin'`, etc.
18
+
This input allows editing record fields that are scalar values, e.g. `123`, `'admin'`, etc.
19
19
20
20
## Usage
21
21
@@ -32,8 +32,9 @@ import { AutocompleteInput } from 'react-admin';
32
32
```
33
33
34
34
By default, the possible choices are built from the `choices` prop, using:
35
-
- the `id` field as the option value,
36
-
- the `name` field as the option text
35
+
36
+
- the `id` field as the option value,
37
+
- the `name` field as the option text
37
38
38
39
The form value for the source must be the selected value, e.g.
39
40
@@ -47,12 +48,12 @@ The form value for the source must be the selected value, e.g.
47
48
48
49
**Tip**: React-admin includes other components to edit such values:
49
50
50
-
-[`<SelectInput>`](./SelectInput.md) renders a dropdown
51
-
-[`<RadioButtonGroupInput>`](./RadioButtonGroupInput.md) renders a list of radio buttons
51
+
-[`<SelectInput>`](./SelectInput.md) renders a dropdown
52
+
-[`<RadioButtonGroupInput>`](./RadioButtonGroupInput.md) renders a list of radio buttons
52
53
53
54
**Tip**: If you need to let users select more than one item in the list, check out the [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md) component.
54
55
55
-
**Tip**: If users need to compare multiple fields before choosing (e.g. team, region, SLA, status), use [`<DataTableInput>`](./DataTableInput.md)<imgclass="icon"src="./img/premium.svg"alt="React Admin Enterprise Edition icon" />.
56
+
**Tip**: If users need to compare multiple fields before choosing (e.g. team, region, SLA, status), use [`<DataTableInput>`](./DataTableInput.md).
56
57
57
58
## Props
58
59
@@ -154,6 +155,7 @@ To allow users to add new options, pass a React element as the `create` prop. `<
154
155
</video>
155
156
156
157
{% raw %}
158
+
157
159
```jsx
158
160
import {
159
161
Create,
@@ -220,6 +222,7 @@ const CreateAuthor = () => {
220
222
);
221
223
};
222
224
```
225
+
223
226
{% endraw %}
224
227
225
228
**Tip**: In development with `React.StrictMode`, you may run into an issue where the `<AutocompleteInput>` menu reopens after clicking the create item when the [`openOnFocus`](https://mui.com/material-ui/api/autocomplete/#autocomplete-prop-openOnFocus) prop is set to `true` which is the default with React-admin. If that bothers you, set the `openOnFocus` prop to `false`.
@@ -317,7 +320,7 @@ If the input isn't required (using `validate={required()}`), and you need a choi
317
320
318
321
The `emptyText` prop accepts either a string or a React Element.
319
322
320
-
And if you want to hide that empty choice, make the input required.
323
+
And if you want to hide that empty choice, make the input required.
**Tip**: While you can set `emptyValue` to a non-string value (e.g. `0`), you cannot use `null` or `undefined`, as it would turn the `<AutocompleteInput>` into an [uncontrolled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components). If you need the empty choice to be stored as `null` or `undefined`, use [the `parse` prop](./Inputs.md#parse) to convert the default empty value ('') to `null` or `undefined`, or use [the `sanitizeEmptyValues` prop](./SimpleForm.md#sanitizeemptyvalues) on the Form component.
339
+
**Tip**: While you can set `emptyValue` to a non-string value (e.g. `0`), you cannot use `null` or `undefined`, as it would turn the `<AutocompleteInput>` into an [uncontrolled component](https://react.dev/learn/sharing-state-between-components#controlled-and-uncontrolled-components). If you need the empty choice to be stored as `null` or `undefined`, use [the `parse` prop](./Inputs.md#parse) to convert the default empty value ('') to `null` or `undefined`, or use [the `sanitizeEmptyValues` prop](./SimpleForm.md#sanitizeemptyvalues) on the Form component.
337
340
338
341
## `filterToQuery`
339
342
340
343
When used inside a [`<ReferenceInput>`](./ReferenceInput.md), whenever users type a string in the autocomplete input, `<AutocompleteInput>` calls `dataProvider.getList()` using the string as filter, to return a filtered list of possible options from the reference resource. This filter is built using the `filterToQuery` prop.
341
344
342
345
By default, the filter is built using the `q` parameter. This means that if the user types the string 'lorem', the filter will be `{ q: 'lorem' }`.
343
346
344
-
You can customize the filter by setting the `filterToQuery` prop. It should be a function that returns a filter object.
347
+
You can customize the filter by setting the `filterToQuery` prop. It should be a function that returns a filter object.
@@ -692,9 +697,11 @@ In that case, set the `translateChoice` prop to `false`.
692
697
`<AutocompleteInput>` renders a [Material UI `<Autocomplete>` component](https://mui.com/material-ui/react-autocomplete/) and it accepts the `<Autocomplete>` props:
The `isPending` prop is used to display a loading indicator while the data is being fetched.
723
730
724
-
However, most of the time, if you need to populate a `<AutocompleteInput>` with choices fetched from another resource, it's because you are trying to set a foreign key. In that case, you should use [`<ReferenceInput>`](./ReferenceInput.md) to fetch the choices instead (see next section).
731
+
However, most of the time, if you need to populate a `<AutocompleteInput>` with choices fetched from another resource, it's because you are trying to set a foreign key. In that case, you should use [`<ReferenceInput>`](./ReferenceInput.md) to fetch the choices instead (see next section).
725
732
726
733
## Selecting a Foreign Key
727
734
728
-
If you use `<AutocompleteInput>` to set a foreign key for a many-to-one or a one-to-one relationship, you'll have to [fetch choices](#fetching-choices), as explained in the previous section. You'll also have to fetch the record corresponding to the current value of the foreign key, as it may not be in the list of choices.
735
+
If you use `<AutocompleteInput>` to set a foreign key for a many-to-one or a one-to-one relationship, you'll have to [fetch choices](#fetching-choices), as explained in the previous section. You'll also have to fetch the record corresponding to the current value of the foreign key, as it may not be in the list of choices.
729
736
730
737
For example, if a `contact` has one `company` via the `company_id` foreign key, a contact form can let users select a company as follows:
**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child input (`<AutocompleteInput>`). `<ReferenceInput>` doesn't accept validation props.
784
791
785
792
`<ReferenceInput>` is a headless component that:
786
-
787
-
- fetches a list of records with `dataProvider.getList()` and `dataProvider.getOne()`, using the `reference` prop for the resource,
788
-
- puts the result of the fetch in the `ChoiceContext` as the `choices` prop, as well as the `isPending` state,
789
-
- and renders its child component
793
+
794
+
- fetches a list of records with `dataProvider.getList()` and `dataProvider.getOne()`, using the `reference` prop for the resource,
795
+
- puts the result of the fetch in the `ChoiceContext` as the `choices` prop, as well as the `isPending` state,
796
+
- and renders its child component
790
797
791
798
When rendered as a child of `<ReferenceInput>`, `<AutocompleteInput>` reads that `ChoiceContext` to populate its own `choices` and `isPending` props. It also sends the current input prop to the `useGetList` hook, so that the list of choices is filtered as the user types.
792
799
793
800
In fact, you can simplify the code even further:
794
801
795
802
-`<ReferenceInput>` puts all its props inside the `ChoiceContext`, including `source`, so `<AutocompleteInput>` doesn't need to repeat it.
796
-
- You can also put the `label` prop on the `<ReferenceInput>` rather than `<AutocompleteInput>` so that it looks just like [`<ReferenceField>`](./ReferenceField.md) (for easier memorization).
797
-
-`<AutocompleteInput>` uses the [`recordRepresentation`](./Resource.md#recordrepresentation) to determine how to represent the related choices. In the example above, the `companies` resource uses `name` as its `recordRepresentation`, so `<AutocompleteInput>` will default to `optionText="name"`.
803
+
- You can also put the `label` prop on the `<ReferenceInput>` rather than `<AutocompleteInput>` so that it looks just like [`<ReferenceField>`](./ReferenceField.md) (for easier memorization).
804
+
-`<AutocompleteInput>` uses the [`recordRepresentation`](./Resource.md#recordrepresentation) to determine how to represent the related choices. In the example above, the `companies` resource uses `name` as its `recordRepresentation`, so `<AutocompleteInput>` will default to `optionText="name"`.
798
805
-`<ReferenceInput>`'s default child is `<AutocompleteInput>`, so you can omit it entirely.
799
806
800
807
The code for the `<CompanyInput>` component can be reduced to:
@@ -895,6 +902,7 @@ The `<AutocompleteInput>` can allow users to create a new choice if either the `
895
902
Use the `onCreate` prop when you only require users to provide a simple string and a `prompt` is enough. You can return either the new choice directly or a Promise resolving to the new choice.
Use the `create` prop when you want a more polished or complex UI. For example a Material UI `<Dialog>` asking for multiple fields because the choices are from a referenced resource.
**Tip:** As showcased in this example, react-admin provides a convenient hook for accessing the filter the user has already input in the `<AutocompleteInput>`: `useCreateSuggestionContext`.
999
1010
1000
1011
The `Create %{item}` option will only be displayed once the user has already set a filter (by typing in some input). If you expect your users to create new items often, you can make this more user-friendly by adding a placeholder text like this:
0 commit comments