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
+30-24
Original file line number
Diff line number
Diff line change
@@ -22,11 +22,23 @@ import { AutocompleteInput } from 'react-admin';
22
22
]} />
23
23
```
24
24
25
+
**Tip**: If you want to populate the `choices` attribute with a list of related records, you should decorate `<AutocompleteInput>` with [`<ReferenceInput>`](./ReferenceInput.md), and leave the `choices` empty:
**Tip**: `<AutocompleteInput>` is a stateless component, so it only allows to *filter* the list of choices, not to *extend* it. If you need to populate the list of choices based on the result from a `fetch` call (and if [`<ReferenceInput>`](./ReferenceInput.md) doesn't cover your need), you'll have to [write your own Input component](./Inputs.md#writing-your-own-input-component) based on MUI `<AutoComplete>` component.
|`choices`|Required|`Object[]`|`-`| List of items to autosuggest|
41
+
|`choices`|Optional|`Object[]`|`-`| List of items to autosuggest. Required if not inside a ReferenceInput.|
30
42
|`create`| Optional |`Element`|`-`| A React Element to render when users want to create a new choice |
31
43
|`createItemLabel`| Optional |`string`|`ra.action.create_item`| The label for the menu item allowing users to create a new choice. Used when the filter is not empty |
32
44
|`emptyValue`| Optional |`any`|`''`| The value to use for the empty element |
@@ -37,13 +49,13 @@ import { AutocompleteInput } from 'react-admin';
37
49
|`optionValue`| Optional |`string`|`id`| Field name of record containing the value to use as input value |
38
50
|`inputText`| Optional |`Function`|`-`| Required if `optionText` is a custom Component, this function must return the text displayed for the current selection. |
39
51
|`filterToQuery`| Optional |`string` => `Object`|`searchText => ({ q: [searchText] })`| How to transform the searchText into a parameter for the data provider |
40
-
|`setFilter`| Optional |`Function`|`null`| A callback to inform the `searchText` has changed and new `choices` can be retrieved based on this `searchText`. Signature `searchText => void`. This function is automatically setup when using `ReferenceInput`. |
52
+
|`setFilter`| Optional |`Function`|`null`| A callback to inform the `searchText` has changed and new `choices` can be retrieved based on this `searchText`. Signature `searchText => void`. This function is automatically set up when using `ReferenceInput`. |
41
53
|`shouldRenderSuggestions`| Optional |`Function`|`() => true`| A function that returns a `boolean` to determine whether or not suggestions are rendered. Use this when working with large collections of data to improve performance and user experience. This function is passed into the underlying react-autosuggest component. Ex.`(value) => value.trim().length > 2`|
42
54
|`suggestionLimit`| Optional |`number`|`null`| Limits the numbers of suggestions that are shown in the dropdown list |
43
55
44
56
`<AutocompleteInput>` also accepts the [common input props](./Inputs.md#common-input-props).
45
57
46
-
## Usage
58
+
## `optionText`
47
59
48
60
You can customize the properties to use for the option name and value, thanks to the `optionText` and `optionValue` attributes:
`optionText` also accepts a custom Component. However, as the underlying Autocomplete component requires that the current selection is a string, if you opt for a Component, you must pass a function as the `inputText` prop. This function should return text representation of the current selection:
81
+
`optionText` also accepts a custom Component. However, as the underlying Autocomplete component requires that the current selection is a string, if you opt for a Component, you must pass a function as the `inputText` prop. This function should return a text representation of the current selection:
When dealing with a large amount of `choices` you may need to limit the number of suggestions that are rendered in order to maintain usable performance. The `shouldRenderSuggestions` is an optional prop that allows you to set conditions on when to render suggestions. An easy way to improve performance would be to skip rendering until the user has entered 2 or 3 characters in the search box. This lowers the result set significantly, and might be all you need (depending on your data set).
129
+
## `shouldRenderSuggestions`
130
+
131
+
When dealing with a large amount of `choices` you may need to limit the number of suggestions that are rendered in order to maintain usable performance. The `shouldRenderSuggestions` is an optional prop that allows you to set conditions on when to render suggestions. An easy way to improve performance would be to skip rendering until the user has entered 2 or 3 characters in the search box. This lowers the result set significantly and might be all you need (depending on your data set).
116
132
Ex. `<AutocompleteInput shouldRenderSuggestions={(val) => { return val.trim().length > 2 }} />` would not render any suggestions until the 3rd character has been entered. This prop is passed to the underlying `react-autosuggest` component and is documented [here](https://github.com/moroshko/react-autosuggest#should-render-suggestions-prop).
117
133
134
+
## `sx`: CSS API
135
+
136
+
This component doesn't apply any custom styles on top of [MUI `<Autocomplete>` component](https://mui.com/components/autocomplete/). Refer to their documentation to know its CSS API.
137
+
138
+
## Additional Props
139
+
118
140
`<AutocompleteInput>` renders a [MUI `<Autocomplete>` component](https://mui.com/components/autocomplete/) and it accepts the `<Autocomplete>` props:
**Tip**: If you want to populate the `choices` attribute with a list of related records, you should decorate `<AutocompleteInput>` with [`<ReferenceInput>`](./ReferenceInput.md), and leave the `choices` empty:
**Tip**: `<AutocompleteInput>` is a stateless component, so it only allows to *filter* the list of choices, not to *extend* it. If you need to populate the list of choices based on the result from a `fetch` call (and if [`<ReferenceInput>`](./ReferenceInput.md) doesn't cover your need), you'll have to [write your own Input component](./Inputs.md#writing-your-own-input-component) based on MUI `<AutoComplete>` component.
137
-
138
148
## Creating New Choices
139
149
140
150
The `<AutocompleteInput>` can allow users to create a new choice if either the `create` or `onCreate` prop is provided.
@@ -171,7 +181,7 @@ const PostCreate = () => {
171
181
```
172
182
{% endraw %}
173
183
174
-
Use the `create` prop when you want a more polished or complex UI. For example a MUI `<Dialog>` asking for multiple fields because the choices are from a referenced resource.
184
+
Use the `create` prop when you want a more polished or complex UI. For example an MUI `<Dialog>` asking for multiple fields because the choices are from a referenced resource.
**Tip:** As showcased in this example, react-admin provides a convenience hook for accessing the filter the user has already input in the `<AutocompleteInput>`: `useCreateSuggestionContext`.
266
+
**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`.
257
267
258
-
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 userfriendly by adding a placeholder text like this:
268
+
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:
259
269
260
270
{% raw %}
261
271
```diff
@@ -287,7 +297,3 @@ const PostCreate = () => {
287
297
}
288
298
```
289
299
{% endraw %}
290
-
291
-
## `sx`: CSS API
292
-
293
-
This component doesn't apply any custom styles on top of [MUI `<Autocomplete>` component](https://mui.com/components/autocomplete/). Refer to their documentation to know its CSS API.
0 commit comments