Skip to content

Commit 10d9c11

Browse files
committed
Misc adjustments
1 parent 430d951 commit 10d9c11

7 files changed

Lines changed: 178 additions & 98 deletions

File tree

docs/AutocompleteInput.md

Lines changed: 31 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ It renders using [Material UI's `<Autocomplete>`](https://mui.com/material-ui/re
1515
Your browser does not support the video tag.
1616
</video>
1717

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.
1919

2020
## Usage
2121

@@ -32,8 +32,9 @@ import { AutocompleteInput } from 'react-admin';
3232
```
3333

3434
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
3738

3839
The form value for the source must be the selected value, e.g.
3940

@@ -47,12 +48,12 @@ The form value for the source must be the selected value, e.g.
4748

4849
**Tip**: React-admin includes other components to edit such values:
4950

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
5253

5354
**Tip**: If you need to let users select more than one item in the list, check out the [`<AutocompleteArrayInput>`](./AutocompleteArrayInput.md) component.
5455

55-
**Tip**: If users need to compare multiple fields before choosing (e.g. team, region, SLA, status), use [`<DataTableInput>`](./DataTableInput.md)<img class="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).
5657

5758
## Props
5859

@@ -154,6 +155,7 @@ To allow users to add new options, pass a React element as the `create` prop. `<
154155
</video>
155156

156157
{% raw %}
158+
157159
```jsx
158160
import {
159161
Create,
@@ -220,6 +222,7 @@ const CreateAuthor = () => {
220222
);
221223
};
222224
```
225+
223226
{% endraw %}
224227

225228
**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
317320

318321
The `emptyText` prop accepts either a string or a React Element.
319322

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.
321324

322325
```jsx
323326
<AutocompleteInput source="author_id" choices={choices} validate={required()} />
@@ -333,15 +336,15 @@ You can override this value with the `emptyValue` prop.
333336
<AutocompleteInput source="author_id" choices={choices} emptyValue={0} />
334337
```
335338

336-
**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.
337340

338341
## `filterToQuery`
339342

340343
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.
341344

342345
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' }`.
343346

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.
345348

346349
```jsx
347350
const filterToQuery = searchText => ({ name_ilike: `%${searchText}%` });
@@ -410,6 +413,7 @@ type OnChange = (
410413
In the following example, the `onChange` prop is used to update the `language` field whenever the user selects a new author:
411414

412415
{% raw %}
416+
413417
```tsx
414418
import * as React from 'react';
415419
import {
@@ -456,11 +460,12 @@ const BookCreate = () => (
456460
</Create>
457461
);
458462
```
463+
459464
{% endraw %}
460465

461466
## `onCreate`
462467

463-
Use the `onCreate` prop to allow users to create new options on the fly. This is equivalent to MUI's `<AutoComplete freeSolo>` prop.
468+
Use the `onCreate` prop to allow users to create new options on the fly. This is equivalent to MUI's `<AutoComplete freeSolo>` prop.
464469

465470
<video controls playsinline muted>
466471
<source src="./img/AutocompleteInput-onCreate.mp4" type="video/mp4"/>
@@ -692,9 +697,11 @@ In that case, set the `translateChoice` prop to `false`.
692697
`<AutocompleteInput>` renders a [Material UI `<Autocomplete>` component](https://mui.com/material-ui/react-autocomplete/) and it accepts the `<Autocomplete>` props:
693698

694699
{% raw %}
700+
695701
```jsx
696702
<AutocompleteInput source="category" size="large" />
697703
```
704+
698705
{% endraw %}
699706

700707
## Fetching Choices
@@ -721,11 +728,11 @@ const CountryInput = () => {
721728

722729
The `isPending` prop is used to display a loading indicator while the data is being fetched.
723730

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).
725732

726733
## Selecting a Foreign Key
727734

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.
729736

730737
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:
731738

@@ -783,18 +790,18 @@ const CompanyInput = () => (
783790
**Tip**: If you need validation (e.g. `required()`), put the `validate` prop on the child input (`<AutocompleteInput>`). `<ReferenceInput>` doesn't accept validation props.
784791

785792
`<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
790797

791798
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.
792799

793800
In fact, you can simplify the code even further:
794801

795802
- `<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"`.
798805
- `<ReferenceInput>`'s default child is `<AutocompleteInput>`, so you can omit it entirely.
799806

800807
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 `
895902
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.
896903

897904
{% raw %}
905+
898906
```js
899907
import { AutocompleteInput, Create, SimpleForm, TextInput } from 'react-admin';
900908

@@ -922,11 +930,13 @@ const PostCreate = () => {
922930
);
923931
}
924932
```
933+
925934
{% endraw %}
926935

927936
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.
928937

929938
{% raw %}
939+
930940
```js
931941
import {
932942
AutocompleteInput,
@@ -993,13 +1003,15 @@ const CreateCategory = () => {
9931003
);
9941004
};
9951005
```
1006+
9961007
{% endraw %}
9971008

9981009
**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`.
9991010

10001011
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:
10011012

10021013
{% raw %}
1014+
10031015
```diff
10041016
const PostCreate = () => {
10051017
const categories = [
@@ -1028,4 +1040,5 @@ const PostCreate = () => {
10281040
);
10291041
}
10301042
```
1043+
10311044
{% endraw %}

0 commit comments

Comments
 (0)