---
layout: default
title: "Input Components"
---
# Input Components
An `Input` component displays an input, or a dropdown list, a list of radio buttons, etc. Such components allow to edit a record property, and are common in the ``, ``, and `` views.
```js
// in src/posts.js
import React from 'react';
import { Edit, DisabledInput, LongTextInput, ReferenceInput, SelectInput, SimpleForm, TextInput } from 'admin-on-rest/lib/mui';
export const PostEdit = (props) => (
} {...props}>
);
```
All input components accept the following attributes:
* `source`: Property name of your entity to view/edit. This attribute is required.
* `defaultValue`: Value to be set when the property is `null` or `undefined`.
* `validation`: Validation rules for the current property (see the [Validation Documentation](./CreateEdit.html#validation))
* `label`: Used as a table header of an input label. Defaults to the `source` when omitted.
* `style`: A style object to customize the look and feel of the field container (e.g. the `
` in a form).
* `elStyle`: A style object to customize the look and feel of the field element itself
Some other props are progressively implemented. The `` and `` inputs also accept following props:
* `onBlur`: a function to call when the form field loses focus. It expects to either receive the [React SyntheticEvent](https://facebook.github.io/react/docs/events.html), or the current value of the field.
* `onChange`: a function to call when the form field is changed. It expects to either receive the [React SyntheticEvent](https://facebook.github.io/react/docs/events.html), or the new value of the field.
* `onFocus`: a function to call when the field receives focus. It takes the `event` as argument.
```js
```
**Tip**: If you edit a record with a complex structure, you can use a path as the `source` parameter. For instance, if the API returns the following 'book' record:
```js
{
id: 1234,
title: 'War and Peace',
author: {
firstName: 'Leo',
lastName: 'Tolstoi'
}
}
```
Then you can display a text input to edit the author first name as follows:
```js
```
**Tip**: If your interface has to support multiple languages, don't use the `label` prop, and put the localized labels in a dictionary instead. See the [Translation documentation](./Translation.html#translating-resource-and-field-names) for details.
## ``
To let users choose a value in a list using a dropdown with autocompletion, use ``. It renders using [Material ui's `` component](http://www.material-ui.com/#/components/auto-complete) and a `fuzzySearch` filter. Set the `choices` attribute to determine the options list (with `id`, `name` tuples).
```js
import { AutocompleteInput } from 'admin-on-rest/lib/mui';
```
You can also customize the properties to use for the option name and value, thanks to the `optionText` and `optionValue` attributes:
```js
const choices = [
{ _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
{ _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
```
`optionText` also accepts a function, so you can shape the option text at will:
```js
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}`;
```
You can customize the `filter` function used to filter the results. By default, it's `AutoComplete.fuzzyFilter`, but you can use any of [the functions provided by `AutoComplete`](http://www.material-ui.com/#/components/auto-complete), or a function of your own (`(searchText: string, key: string) => boolean`):
```js
import { AutocompleteInput } from 'admin-on-rest/lib/mui';
import AutoComplete from 'material-ui/AutoComplete';
```
Lastly, use the `options` attribute if you want to override any of Material UI's `` attributes:
{% raw %}
```js
```
{% endraw %}
Refer to [Material UI Autocomplete documentation](http://www.material-ui.com/#/components/auto-complete) for more details.
**Tip**: If you want to populate the `choices` attribute with a list of related records, you should decorate `` with [``](#referenceinput), and leave the `choices` empty:
```js
import { AutocompleteInput, ReferenceInput } from 'admin-on-rest/lib/mui'
```
**Tip**: `` 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) doesn't cover your need), you'll have to [write your own Input component](#writing-your-own-input-component) based on material-ui `` component.
**Tip**: Admin-on-rest's `` has only a capital A, while material-ui's `` has a capital A and a capital C. Don't mix up the components!
## `` and ``
`` is a toggle button allowing you to attribute a `true` or `false` value to a record field.
``` js
import { BooleanInput } from 'admin-on-rest/lib/mui';
```
This input does not handle `null` values. You would need the `` component if you have to handle non-set booleans.
`` renders as a dropdown list, allowing to choose between true, false, and null values.
``` js
import { NullableBooleanInput } from 'admin-on-rest/lib/mui';
```
## ``
If you want to let the user choose multiple values among a list of possible values by showing them all, `` is the right component. Set the `choices` attribute to determine the options (with `id`, `name` tuples):
```js
import { CheckboxGroupInput } from 'admin-on-rest/lib/mui';
```
You can also customize the properties to use for the option name and value, thanks to the `optionText` and `optionValue` attributes:
```js
const choices = [
{ _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
{ _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
```
`optionText` also accepts a function, so you can shape the option text at will:
```js
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}`;
```
`optionText` also accepts a React Element, that will be cloned and receive the related choice as the `record` prop. You can use Field components there.
```js
const choices = [
{ id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
{ id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const FullNameField = ({ record }) => {record.first_name} {record.last_name};
}/>
```
Lastly, use the `options` attribute if you want to override any of Material UI's `` attributes:
{% raw %}
```js
```
{% endraw %}
Refer to [Material UI Checkbox documentation](http://www.material-ui.com/#/components/checkbox) for more details.
## ``
Ideal for editing dates, `` renders a beautiful [Date Picker](http://www.material-ui.com/#/components/date-picker) with full localization support.
``` js
import { DateInput } from 'admin-on-rest/lib/mui';
```
You can override any of Material UI's `` attributes by setting the `options` attribute:
{% raw %}
``` js
```
{% endraw %}
Refer to [Material UI Datepicker documentation](http://www.material-ui.com/#/components/date-picker) for more details.
## ``
When you want to display a record property in an `` form without letting users update it (such as for auto-incremented primary keys), use the ``:
``` js
import { DisabledInput } from 'admin-on-rest/lib/mui';
```
**Tip**: To add non-editable fields to the `` view, you can also use one of admin-on-rest `Field` components:
```js
// in src/posts.js
import { Edit, LongTextInput, SimpleForm, TextField } from 'admin-on-rest/lib/mui';
export const PostEdit = (props) => (
{/* NOT EDITABLE */}
);
```
**Tip**: You can even use a component of your own, provided it accepts a `record` prop:
```js
// in src/posts.js
import { Edit, LongTextInput, SimpleForm } from 'admin-on-rest/lib/mui';
const titleStyle = { textOverflow: 'ellipsis', overflow: 'hidden', maxWidth: '20em' };
const Title = ({ record }) => {record.title};
Title.defaultProps = {
addLabel: true,
};
export const PostEdit = (props) => (
);
```
## ``
`` allows to upload some pictures using [react-dropzone](https://github.com/okonet/react-dropzone).
Previews are enabled using `` children, as following:
``` js
```
This component accepts all [react-dropzone properties](https://github.com/okonet/react-dropzone#features), in addition to those of admin-on-rest. For instance, if you need to upload several images at once, just add the `multiple` DropZone attribute to your `` field.
If the default Dropzone label don't fit with your need, you can pass a `placeholder` attribute to overwrite it. The attribute can be anything React can render (`React.PropTypes.node`):
``` js
Drop your file here}>
```
Note that the image upload returns a [File](https://developer.mozilla.org/en/docs/Web/API/File) object. It is your responsibility to handle it depending on your API behavior. You can for instance encode it in base64, or send it as a multi-part form data. Check [this example](./RestClients.html#decorating-your-rest-client-example-of-file-upload) for base64 encoding data by extending the REST Client.
## ``
`` is the best choice for multiline text values. It renders as an auto expandable textarea.
``` js
import { LongTextInput } from 'admin-on-rest/lib/mui';
```
## ``
`` translates to a HTMl ``. It is necessary for numeric values because of a [known React bug](https://github.com/facebook/react/issues/1425), which prevents using the more generic [``](#textinput) in that case.
``` js
import { NumberInput } from 'admin-on-rest/lib/mui';
```
You can customize the `step` props (which defaults to "any"):
``` js
```
## ``
If you want to let the user choose a value among a list of possible values by showing them all (instead of hiding them behind a dropdown list, as in [``](#selectinput)), `` is the right component. Set the `choices` attribute to determine the options (with `id`, `name` tuples):
```js
import { RadioButtonGroupInput } from 'admin-on-rest/lib/mui';
```
You can also customize the properties to use for the option name and value, thanks to the `optionText` and `optionValue` attributes:
```js
const choices = [
{ _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
{ _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
```
`optionText` also accepts a function, so you can shape the option text at will:
```js
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}`;
```
`optionText` also accepts a React Element, that will be cloned and receive the related choice as the `record` prop. You can use Field components there.
```js
const choices = [
{ id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
{ id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const FullNameField = ({ record }) => {record.first_name} {record.last_name};
}/>
```
Lastly, use the `options` attribute if you want to override any of Material UI's `` attributes:
{% raw %}
```js
```
{% endraw %}
Refer to [Material UI SelectField documentation](http://www.material-ui.com/#/components/radio-button) for more details.
**Tip**: If you want to populate the `choices` attribute with a list of related records, you should decorate `` with [``](#referenceinput), and leave the `choices` empty:
```js
import { RadioButtonGroupInput, ReferenceInput } from 'admin-on-rest/lib/mui'
```
## ``
Use `` for foreign-key values, i.e. to let users choose a value from another REST endpoint. This component fetches the possible values in the reference resource (using the `GET_LIST` REST method), then delegates rendering to a subcomponent, to which it passes the possible choices as the `choices` attribute.
This means you can use `` with any of [``](#selectinput), [``](#autocompleteinput), or [``](#radiobuttongroupinput), or even with the component of your choice, provided it supports the `choices` attribute.
The component expects a `source` and a `reference` attributes. For instance, to make the `post_id` for a `comment` editable:
```js
import { ReferenceInput, SelectInput } from 'admin-on-rest/lib/mui'
```
Set the `allowEmpty` prop when the empty value is allowed.
```js
import { ReferenceInput, SelectInput } from 'admin-on-rest/lib/mui'
```
**Tip**: `allowEmpty` is set by default for all Input components children of the `` component:
```js
const CommentFilter = (props) => (
// no need for allowEmpty
);
```
You can tweak how this component fetches the possible values using the `perPage`, `sort`, and `filter` props.
{% raw %}
```js
// by default, fetches only the first 25 values. You can extend this limit
// by setting the `perPage` prop.
// by default, orders the possible values by id desc. You can change this order
// by setting the `sort` prop (an object with `field` and `order` properties).
// you can filter the query used to populate the possible values. Use the
// `filter` prop for that.
```
{% endraw %}
The enclosed component may further filter results (that's the case, for instance, for ``). ReferenceInput passes a `setFilter` function as prop to its child component. It uses the value to create a filter for the query - by default `{ q: [searchText] }`. You can customize the mapping
`searchText => searchQuery` by setting a custom `filterToQuery` function prop:
```js
({ title: searchText })}>
```
## ``
`` is the ideal component if you want to allow your users to edit some HTML contents. It
is powered by [Quill](https://quilljs.com/).
**Note**: Due to its size, `` is not bundled by default with admin-on-rest. You must install it first, using npm:
```sh
npm install aor-rich-text-input --save
```
Then use it as a normal input component:
``` js
import RichTextInput from 'aor-rich-text-input';
```
You can customize the rich text editor toolbar using the `toolbar` attribute, as described on the [Quill official toolbar documentation](https://quilljs.com/docs/modules/toolbar/).
```js
```
## ``
To let users choose a value in a list using a dropdown, use ``. It renders using [Material ui's ``](http://www.material-ui.com/#/components/select-field). Set the `choices` attribute to determine the options (with `id`, `name` tuples):
```js
import { SelectInput } from 'admin-on-rest/lib/mui';
```
You can also customize the properties to use for the option name and value, thanks to the `optionText` and `optionValue` attributes:
```js
const choices = [
{ _id: 123, full_name: 'Leo Tolstoi', sex: 'M' },
{ _id: 456, full_name: 'Jane Austen', sex: 'F' },
];
```
`optionText` also accepts a function, so you can shape the option text at will:
```js
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}`;
```
`optionText` also accepts a React Element, that will be cloned and receive the related choice as the `record` prop. You can use Field components there.
```js
const choices = [
{ id: 123, first_name: 'Leo', last_name: 'Tolstoi' },
{ id: 456, first_name: 'Jane', last_name: 'Austen' },
];
const FullNameField = ({ record }) => {record.first_name} {record.last_name};
}/>
```
Enabling the `allowEmpty` props adds an empty choice (with `null` value) on top of the options, and makes the value nullable:
```js
```
Lastly, use the `options` attribute if you want to override any of Material UI's `` attributes:
{% raw %}
```js
```
{% endraw %}
Refer to [Material UI SelectField documentation](http://www.material-ui.com/#/components/select-field) for more details.
**Tip**: If you want to populate the `choices` attribute with a list of related records, you should decorate `` with [``](#referenceinput), and leave the `choices` empty:
```js
import { SelectInput, ReferenceInput } from 'admin-on-rest/lib/mui'
```
If, instead of showing choices as a dropdown list, you prefer to display them as a list of radio buttons, try the [``](#radiobuttongroupinput). And if the list is too big, prefer the [``](#autocompleteinput).
## ``
`` is the most common input. It is used for texts, emails, URL or passwords. In translates to an HTML `` tag.
``` js
import { TextInput } from 'admin-on-rest/lib/mui';
```
You can choose a specific input type using the `type` attribute, for instance `text` (the default), `email`, `url`, or `password`:
``` js
```
**Warning**: Do not use `type="number"`, or you'll receive a string as value (this is a [known React bug](https://github.com/facebook/react/issues/1425)). Instead, use [``](#numberinput).
## Transforming Input Value to/from Store
The data format returned by the input component may not be what your store desires. Since Admin-on-rest uses Redux Form, we can use its `parse()` and `format()` functions to transform the input value to and from the store. It's better to understand the [input value's lifecycle](http://redux-form.com/6.5.0/docs/ValueLifecycle.md/) before you start.
Mnemonic for the two functions:
- `parse()`: input -> store
- `format()`: store -> input
Say the user would like to input values of 0-100 to a percentage field but your API (hence store) expects 0-1.0. You can use simple `parse()` and `format()` functions to archive the transform:
```js
v*100} parse={v => v/100} label="Formatted number" />
```
`` stores and returns a `Date` object. If you would like to store the ISO date `"YYYY-MM-DD"` in your store:
```js
const dateFormatter = v => {
// v is a string of "YYYY-MM-DD" format
const match = /(\d{4})-(\d{2})-(\d{2})/.exec(v);
if (match === null) return;
const d = new Date(match[1], parseInt(match[2])-1, match[3]);
if (isNaN(d)) return;
return d;
};
const dateParser = v => {
// v is a `Date` object
if (!(v instanceof Date) || isNaN(v)) return;
const pad = '00';
const yy = v.getFullYear().toString();
const mm = ((v.getMonth() + 1).toString();
const dd = v.getDate().toString();
return `${yy}-${(pad + mm).slice(-2)}-${(pad + dd).slice(-2)}`;
};
```
## Third-Party Components
You can find components for admin-on-rest in third-party repositories.
* [dreinke/aor-color-input](https://github.com/dreinke/aor-color-input): a color input using [React Color](http://casesandberg.github.io/react-color/), a collection of color pickers.
* [LoicMahieu/aor-tinymce-input](https://github.com/LoicMahieu/aor-tinymce-input): a TinyMCE component, useful for editing HTML
## Writing Your Own Input Component
If you need a more specific input type, you can also write it yourself. You'll have to rely on redux-form's [``](http://redux-form.com/6.5.0/docs/api/Field.md/) component, so as to handle the value update cycle.
For instance, let's write a component to edit the latitude and longitude of the current record:
```js
// in LatLongInput.js
import { Field } from 'redux-form';
const LatLngInput = () => (
);
export default LatLngInput;
// in ItemEdit.js
const ItemEdit = (props) => (
);
```
`LatLngInput` takes no props, because the `` component can access the current record via its context. The `name` prop serves as a selector for the record property to edit. All `Field` props except `name` and `component` are passed to the child component/element (an `` in that example). Executing this component will render roughly the following code:
```html
```
This component lacks a label. Admin-on-rest provides the `` component for that:
```js
// in LatLongInput.js
import { Field } from 'redux-form';
import { Labeled } from 'admin-on-rest/lib/mui';
const LatLngInput = () => (
);
export default LatLngInput;
```
Now the component will render with a label:
```html
```
Adding a label to an input component is such a common operation that admin-on-rest has the ability to do it automatically: just set the `addLabel` prop, and specify the label in the `label` prop:
```js
// in LatLongInput.js
import { Field } from 'redux-form';
const LatLngInput = () => (
);
export default LatLngInput;
// in ItemEdit.js
const ItemEdit = (props) => (
);
```
**Tip**: To avoid repeating them each time you use the component, you should define `label` and `addLabel` as `defaultProps`:
```js
// in LatLongInput.js
import { Field } from 'redux-form';
const LatLngInput = () => (
);
LatLngInput.defaultProps = {
addLabel: true,
label: 'Position',
}
export default LatLngInput;
// in ItemEdit.js
const ItemEdit = (props) => (
);
```
**Tip**: The `` component supports dot notation in the `name` prop, to edit nested props:
```js
const LatLongInput = () => (
);
```
Instead of HTML `input` elements, you can use admin-on-rest components in ``. For instance, ``:
```js
// in LatLongInput.js
import { Field } from 'redux-form';
import { NumberInput } from 'admin-on-rest/lib/mui';
const LatLngInput = () => (
);
export default LatLngInput;
// in ItemEdit.js
const ItemEdit = (props) => (
);
```
`` receives the props passed to the `` component - `label` in the example. `` is already labelled, so there is no need to also label the `` component - that's why `addLabel` isn't set as default prop this time.
**Tip**: If you need to pass a material ui component to `Field`, use a [field renderer function](http://redux-form.com/6.5.0/examples/material-ui/) to map the props:
```js
import TextField from 'material-ui/TextField';
const renderTextField = ({ input, label, meta: { touched, error }, ...custom }) => (
);
const LatLngInput = () => (
);
```
For more details on how to use redux-form's `` component, please refer to [the redux-form doc](http://redux-form.com/6.5.0/docs/api/Field.md/).
**Tip**: If you only need one `` component in a custom input, you can let admin-on-rest do the `` decoration for you by setting the `addField` default prop to `true`:
```js
// in PersonEdit.js
import SexInput from './SexInput.js';
const PersonEdit = (props) => (
);
// in SexInput.js
import SelectField from 'material-ui/SelectField';
import MenuItem from 'material-ui/MenuItem';
const SexInput = ({ input, meta: { touched, error } }) => (
);
SexInput.defaultProps = {
addField: true, // require a decoration
}
export default SexInput;
// equivalent of
import SelectField from 'material-ui/SelectField';
import MenuItem from 'material-ui/MenuItem';
import { Field } from 'redux-form';
const renderSexInput = ({ input, meta: { touched, error } }) => (
);
const SexInput = ({ source }) =>
export default SexInput;
```
Most admin-on-rest input components use `addField: true` in default props.
**Tip**: `` injects two props to its child component: `input` and `meta`. To learn more about these props, please refer to [the `` component documentation](http://redux-form.com/6.5.0/docs/api/Field.md/#props) in the redux-form website.