<ReferenceArrayInput>

Use<ReferenceArrayInput> to edit an array of reference values, i.e. to let users choose a list of values (usually foreign keys) from another REST endpoint.

Usage

For instance, a post record has atag_ids field, which is an array of foreign keys to tags record.

┌──────────────┐       ┌────────────┐│ post         │       │ tags       ││--------------│       │------------││ id           │   ┌───│ id         ││ title        │   │   │ name       ││ body         │   │   └────────────┘│ tag_ids      │───┘└──────────────┘

To make thetag_ids for apost editable, use the following:

import{Edit,SimpleForm,TextInput,ReferenceArrayInput}from'react-admin';constPostEdit=()=>(<Edit><SimpleForm><TextInputsource="title"/><ReferenceArrayInputsource="tags_ids"reference="tags"/></SimpleForm></Edit>);

<ReferenceArrayInput> requires asource and areference prop.

<ReferenceArrayInput> uses the array of foreign keys to fetch the related records. It also grabs the list of possible choices for the field. For instance, if thePostEdit component above is used to edit the following post:

{id:1234,title:"Lorem Ipsum",body:"Lorem ipsum dolor sit amet, consectetur adipiscing elit.",tag_ids:[1,23,4]}

Then<ReferenceArrayInput> will issue the following queries:

dataProvider.getMany('tags',{ids:[1,23,4]});dataProvider.getList('tags',{filter:{},sort:{field:'id',order:'DESC'},pagination:{page:1,perPage:25}});

<ReferenceArrayInput> renders an<AutocompleteArrayInput> to let the user select the related record. Users can narrow down the choices by typing a search term in the input. This modifies the query sent to thedataProvider as follows:

dataProvider.getList('tags',{filter:{q:['search term']},sort:{field:'id',order:'DESC'},pagination:{page:1,perPage:25}});

SeeCustomizing the filter query below for more information about how to changefilter prop based on the<AutocompleteArrayInput> search term.

You can tweak how<ReferenceArrayInput> fetches the possible values using thepage,perPage,sort, andfilter props.

You can replace the default<AutocompleteArrayInput> with another choice input, by setting a child component. For instance, to use a<SelectArrayInput>:

import{ReferenceArrayInput,SelectArrayInput}from'react-admin';<ReferenceArrayInputsource="tag_ids"reference="tags"><SelectArrayInput/></ReferenceArrayInput>

See thechildren section for more details.

Props

Note:<ReferenceArrayInput> doesn’t accept thecommon input props ; it is the responsability of children to apply them.

children

By default,<ReferenceInput> renders an<AutocompleteArrayInput> to let end users select the reference record.

You can pass a child component to customize the way the reference selector is displayed.

For instance, to customize the input label set thelabel prop on the child component:

import{ReferenceArrayInput,AutocompleteArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputlabel="code"/></ReferenceArrayInput>

The child can be:

• <SelectArrayInput>
• <AutocompleteArrayInput>
• <DualListInput>
• <CheckboxGroupInput>,

import{ReferenceArrayInput,SelectInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><SelectArrayInput/></ReferenceArrayInput>

You can even use a component of your own as child, provided it detects aChoicesContext is available and gets their choices from it.

The choices context value can be accessed with theuseChoicesContext hook.

enableGetChoices

You can make thegetList() call lazy by using theenableGetChoices prop. This prop should be a function that receives thefilterValues as parameter and return a boolean. This can be useful when using an<AutocompleteArrayInput> on a resource with a lot of data. The following example only starts fetching the options when the query has at least 2 characters:

<ReferenceArrayInputsource="tags_ids"reference="tags"enableGetChoices={({q})=>q&&q.length>=2}/>

filter

You can filter the query used to populate the possible values. Use thefilter prop for that.

<ReferenceArrayInputsource="tags_ids"reference="tags"filter={{is_published:true}}/>

Note: When users type a search term in the<AutocompleteArrayInput>, this doesn’t affect thefilter prop. Check theCustomizing the filter query section below for details on how that filter works.

format

If you want to format the input value before displaying it, you have to pass a customformat prop to the<ReferenceArrayInput>child component, because<ReferenceArrayInput> doesn’t have aformat prop. It is the responsibility of the child component to format the input value.

For instance, if you want to transform an option value before rendering, and the selection control is an<AutocompleteArrayInput> (the default), setthe<AutocompleteArrayInput format> prop as follows:

import{ReferenceArrayInput,AutocompleteArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputformat={value=>value==null?'not defined':value}/></ReferenceArrayInput>

The same goes if the child is a<SelectArrayInput>:

import{ReferenceArrayInput,SelectArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><SelectArrayInputformat={value=>value===undefined?'not defined':null}/></ReferenceArrayInput>

label

In an<Edit> or<Create> view, thelabel prop has no effect.<ReferenceArrayInput> has no label, it simply renders its child (an<AutocompleteArrayInput> by default). If you need to customize the label, set thelabel prop on the child element:

import{ReferenceArrayInput,AutocompleteArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputlabel="Post tags"/></ReferenceArrayInput>

In a Filter form, react-admin uses thelabel prop to set the Filter label. So in this case, thelabel prop is not ignored, but you also have to set it on the child input.

constfilters=[<ReferenceArrayInputlabel="Post tags"source="tags_ids"reference="tags"><AutocompleteArrayInputlabel="Post tags"/></ReferenceArrayInput>,];

parse

By default, children of<ReferenceArrayInput> transform the empty form value (an empty string) intonull before passing it to thedataProvider.

If you want to change this behavior, you have to pass a customparse prop to the<ReferenceArrayInput>child component, because<ReferenceArrayInput> doesn’t have aparse prop. It is the responsibility of the child component to parse the input value.

For instance, if you want to transform an option value before submission, and the selection control is an<AutocompleteArrayInput> (the default), setthe<AutocompleteArrayInput parse> prop as follows:

import{ReferenceArrayInput,AutocompleteArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputparse={value=>value==='not defined'?null:value}/></ReferenceArrayInput>

The same goes if the child is a<SelectArrayInput>:

import{ReferenceArrayInput,SelectArrayInput}from'react-admin';<ReferenceArrayInputsource="tags_ids"reference="tags"><SelectArrayInputparse={value=>value==='not defined'?undefined:null}/></ReferenceArrayInput>

perPage

By default,<ReferenceArrayInput> fetches only the first 25 values. You can extend this limit by setting theperPage prop.

<ReferenceArrayInputsource="tags_ids"reference="tags"perPage={100}/>

This prop is mostly useful when using<SelectArrayInput> or<CheckboxGroupInput> as child, as the default<AutocompleteArrayInput> child allows to filter the possible choices with a search input.

queryOptions

Use thequeryOptions prop to pass options to thedataProvider.getList() query that fetches the possible choices.

For instance, to passa custommeta:

<ReferenceArrayInputsource="tag_ids"reference="tags"queryOptions={{meta:{foo:'bar'}}}/>

reference

The name of the reference resource. For instance, in a post form, if you want to edit the post tags, the reference should be “tags”.

<ReferenceArrayInputsource="tags_ids"reference="tags"/>

<ReferenceArrayInput> will use the reference resourcerecordRepresentation to display the selected record and the list of possible records. So for instance, if thetags resource is defined as follows:

<Resourcename="tags"recordRepresentation="name"/>

Then<ReferenceArrayInput> will display the company name in the input and the list of possible values.

You can override this default by specifying theoptionText prop in the child component. For instance, for an<AutocompleteArrayInput>:

<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputoptionText="reference"/></ReferenceArrayInput>

sort

By default,<ReferenceArrayInput> orders the possible values byid desc.

You can change this order by setting thesort prop (an object withfield andorder properties).

<ReferenceArrayInputsource="tag_ids"reference="tags"sort={{field:'name',order:'ASC'}}/>

source

The name of the property in the record that contains the array of identifiers of the selected record.

For instance, if a post contains a reference to tags via atag_ids property:

{id:456,title:"Hello, world!",tag_ids:[123,456]}

Then to display a selector for the post tags, you should call<ReferenceArrayInput> as follows:

<ReferenceArrayInputsource="tags_ids"reference="tags"/>

Customizing The Filter Query

By default,<ReferenceArrayInput> renders an<AutocompleteArrayInput>, which lets users type a search term to filter the possible values.<ReferenceArrayInput> callsdataProvider.getList() using the search term as filter, using the formatfilter: { q: [search term] }.

If you want to customize the conversion between the search term and the query filter to match the filtering capabilities of your API, use the<AutocompleteArrayInput filterToQuery> prop.

constfilterToQuery=searchText=>({name_ilike:`%${searchText}%`});<ReferenceArrayInputsource="tags_ids"reference="tags"><AutocompleteArrayInputfilterToQuery={filterToQuery}/></ReferenceArrayInput>