`<AutocompleteArrayInput>`

To let users choose multiple values in a list using a dropdown with autocompletion, use <AutocompleteArrayInput>. It renders using MUI Autocomplete.

AutocompleteArrayInput

Set the choices attribute to determine the options list (with id, name tuples).

import { AutocompleteArrayInput } from 'react-admin';

<AutocompleteArrayInput source="tags" choices={[
    { id: 'programming', name: 'Programming' },
    { id: 'lifestyle', name: 'Lifestyle' },
    { id: 'photography', name: 'Photography' },
]} />

Properties

Prop	Required	Type	Default	Description
`choices`	Required	`Object[]`	-	List of items to auto-suggest
`create`	Optional	`Element`	`-`	A React Element to render when users want to create a new choice
`createLabel`	Optional	`string`	`ra.action.create`	The label for the menu item allowing users to create a new choice. Used when the filter is empty
`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
`debounce`	Optional	`number`	`250`	The delay to wait before calling the setFilter function injected when used in a ReferenceInput.
`emptyText`	Optional	`string`	`''`	The text to use for the empty element
`emptyValue`	Optional	`any`	`''`	The value to use for the empty element
`inputText`	Optional	`Function`	`-`	Required if `optionText` is a custom Component, this function must return the text displayed for the current selection.
`matchSuggestion`	Optional	`Function`	-	Required if `optionText` is a React element. Function returning a boolean indicating whether a choice matches the filter. `(filter, choice) => boolean`
`onCreate`	Optional	`Function`	`-`	A function called with the current filter value when users choose to create a new choice.
`optionText`	Optional	`string` \| `Function` \| `Component`	`name`	Field name of record to display in the suggestion item or function which accepts the correct record as argument (`(record)=> {string}`)
`optionValue`	Optional	`string`	`id`	Field name of record containing the value to use as input value
`filterToQuery`	Optional	`string` => `Object`	`searchText => ({ q: [searchText] })`	How to transform the searchText into a parameter for the data provider
`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`.
`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 `MUI Autocomplete` component. Ex.`(value) => value.trim().length > 2`
`suggestionLimit`	Optional	`number`	`null`	Limits the numbers of suggestions that are shown in the dropdown list

<AutocompleteArrayInput> also accepts the common input props.

Usage

<AutocompleteArrayInput> is designed to for fields containing an array of scalar values, e.g.:

{
  "id": 123,
  "tags": ["lifestyle", "photography"]
}

When working with a field that contains an array of objects, use parse and format to turn the value into an array of scalar values.

So for instance, for editing the tags field of records looking like the following:

{
  "id": 123,
  "tags": [
      { "id": "lifestyle" },
      { "id": "photography" }
   ] 
}

You should use the following syntax:

import { AutocompleteArrayInput } from 'react-admin';

<AutocompleteArrayInput 
    source="tags"
    parse={value =>
        value && value.map(v => ({ id: v }))
    }
    format={value => value && value.map(v => v.id)}
    choices={[
        { id: 'programming', name: 'Programming' },
        { id: 'lifestyle', name: 'Lifestyle' },
        { id: 'photography', name: 'Photography' },
    ]}
/>

You can customize the properties to use for the option name and value, thanks to the optionText and optionValue attributes:

const choices = [
    { _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
    { _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
<AutocompleteArrayInput source="author_id" choices={choices} optionText="full_name" optionValue="_id" />

optionText also accepts a function, so you can shape the option text at will:

const choices = [
   { id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
   { id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const optionRenderer = choice => `${choice.first_name} ${choice.last_name}`;
<AutocompleteArrayInput source="author_id" choices={choices} optionText={optionRenderer} />

The choices are translated by default, so you can use translation identifiers as choices:

const choices = [
   { id: 'M', name: 'myroot.gender.male' },
   { id: 'F', name: 'myroot.gender.female' },
];

However, in some cases (e.g. inside a <ReferenceInput>), you may not want the choice to be translated. In that case, set the translateChoice prop to false.

<AutocompleteArrayInput source="gender" choices={choices} translateChoice={false}/>

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). Ex. <AutocompleteArrayInput 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.

Lastly, <AutocompleteArrayInput> renders a MUI <Autocomplete> component and accepts the <Autocomplete> props:

<AutocompleteArrayInput source="category" limitTags={2} />

Tip: Like many other inputs, <AutocompleteArrayInput> accept a fullWidth prop.

Tip: If you want to populate the choices attribute with a list of related records, you should decorate <AutocompleteArrayInput> with <ReferenceArrayInput>, and leave the choices empty:

import { AutocompleteArrayInput, ReferenceArrayInput } from 'react-admin';

<ReferenceArrayInput label="Tags" reference="tags" source="tags">
    <AutocompleteArrayInput />
</ReferenceArrayInput>

Tip: <ReferenceArrayInput> 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 <ReferenceArrayInput> doesn’t cover your need), you’ll have to write your own Input component based on material-ui-chip-input.

Tip: React-admin’s <AutocompleteInput> has only a capital A, while MUI’s <AutoComplete> has a capital A and a capital C. Don’t mix up the components!

Creating New Choices

The <AutocompleteArrayInput> can allow users to create a new choice if either the create or onCreate prop is provided.

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.

import { AutocompleteArrayInput, Create, SimpleForm, TextInput } from 'react-admin';

const PostCreate = () => {
    const tags = [
        { name: 'Tech', id: 'tech' },
        { name: 'Lifestyle', id: 'lifestyle' },
    ];
    return (
        <Create>
            <SimpleForm>
                <TextInput source="title" />
                <AutocompleteArrayInput
                    onCreate={() => {
                        const newTagName = prompt('Enter a new tag');
                        const newTag = { id: newTagName.toLowerCase(), name: newTagName };
                        tags.push(newTag);
                        return newTag;
                    }}
                    source="tags"
                    choices={tags}
                />
            </SimpleForm>
        </Create>
    );
}

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.

import {
    AutocompleteArrayInput,
    Create,
    ReferenceArrayInput,
    SimpleForm,
    TextInput,
    useCreate,
    useCreateSuggestionContext
} from 'react-admin';

import {
    Box,
    BoxProps,
    Button,
    Dialog,
    DialogActions,
    DialogContent,
    TextField,
} from '@mui/material';

const PostCreate = () => {
    return (
        <Create>
            <SimpleForm>
                <TextInput source="title" />
                <ReferenceArrayInput source="tags" reference="tags">
                    <AutocompleteArrayInput create={<CreateTag />} />
                </ReferenceArrayInput>
            </SimpleForm>
        </Create>
    );
}

const CreateTag = () => {
    const { filter, onCancel, onCreate } = useCreateSuggestionContext();
    const [value, setValue] = React.useState(filter || '');
    const [create] = useCreate();

    const handleSubmit = event => {
        event.preventDefault();
        create(
            'tags',
            {
                data: {
                    title: value,
                },                
            },
            {
                onSuccess: (data) => {
                    setValue('');
                    onCreate(data);
                },
            }
        );
    };

    return (
        <Dialog open onClose={onCancel}>
            <form onSubmit={handleSubmit}>
                <DialogContent>
                    <TextField
                        label="New tag"
                        value={value}
                        onChange={event => setValue(event.target.value)}
                        autoFocus
                    />
                </DialogContent>
                <DialogActions>
                    <Button type="submit">Save</Button>
                    <Button onClick={onCancel}>Cancel</Button>
                </DialogActions>
            </form>
        </Dialog>
    );
};

`sx`: CSS API

This component doesn’t apply any custom styles on top of MUI <Autocomplete> component. Refer to their documentation to know its CSS API.

<AutocompleteArrayInput>

Properties

Usage

Creating New Choices

sx: CSS API

`<AutocompleteArrayInput>`

`sx`: CSS API