# Form Field Metadata

Each form field in the form array passed to MobxSchemaForm can optionally specify additional metadata that controls the type of widget to use and how it's rendered and whether it's rendered at all:

| prop                                                  | Data type                                                                                                                                                                                                                                                                                                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| key                                                   | String                                                                                                                                                                                                                                                                                                                              | Required except for fieldset and help. Name of the key in schema.properties.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| type                                                  | String                                                                                                                                                                                                                                                                                                                              | One of a list of [built-in widget types](https://alexhisen.gitbook.io/mobx-forms/mobx-schema-form/widget-types) or a custom one that will be mapped to a React component/function in the mapper object passed to MobxSchemaForm.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| placeholder                                           | String                                                                                                                                                                                                                                                                                                                              | Passed to React-Toolbox Datepicker widget (no fallback) and to Input widget (fallback to schema title) in hint                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| default                                               | Any                                                                                                                                                                                                                                                                                                                                 | Overrides schema default                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| titleMap                                              | Array of objects with name (not label!) and value keys (select can also have group key (not yet supported by built-in React-Toolbox Dropdown) or Array of values                                                                                                                                                                    | Required for select, radios and link type fields. Specifies the list of options for React-Toolbox Dropdown, values and optional labels for Radios, optional labels for Switch, the text variants for link. If neither schema, nor field metadata specifies default, the value of the first item in titleMap is used as the default.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| min, max (\*)                                         | String                                                                                                                                                                                                                                                                                                                              | Used by date-type fields to specify the min/max allowed dates in the React-Toolbox Datepicker. These strings are parsed with [sugar](https://sugarjs.com/) and support strings like "today" or "3 weeks from today".                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| min, max, step, tickLabelsStep, tickLabelsFormat (\*) | Number                                                                                                                                                                                                                                                                                                                              | Used by range-type fields. If min or max are not specified here, falls back to minimum and maximum from schema. If step is specified, the default range widget will render tick labels (as unstyled(!) OL/LI tags) under the React-Toolbox Slider control. Set tickLabelsStep to 0 to disable or set it to 2 to render a label every other step tick (currently requires max-min to be even). tickLabelsFormat is an optional function that takes the step number value and returns a formatted result.                                                                                                                                                                                                                                                                                                                                                           |
| props (\*)                                            | Object                                                                                                                                                                                                                                                                                                                              | You can specify any props here that will be passed as-is to the React-Toolbox widget. For example, for select (Dropdown), you can set allowBlank to false and have a { name: "Select state", value: null } as the first item in the titleMap and it'll be selected if the value doesn't match any of the options. You can specify okLabel and cancelLabel strings for date (Datepicker) or set pinned or snaps to false for range (Slider) fields.                                                                                                                                                                                                                                                                                                                                                                                                                |
| mask (\*\*\*)                                         | String                                                                                                                                                                                                                                                                                                                              | An optional mask recognized by [react-input-mask](https://github.com/sanniassin/react-input-mask) component (i.e. "(999) 999-9999"). User input will be formatted according to the mask on the fly. Only applicable to text / tel / number widgets (the property type should be *string* and it should not have a maxLength).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| maskProps (\*\*\*)                                    | Object                                                                                                                                                                                                                                                                                                                              | You can specify any props here that will be passed as-is to the [react-input-mask](https://github.com/sanniassin/react-input-mask) component (i.e. maskChar, alwaysShowMask, etc).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| validations (\*)                                      | Array of Functions or String keywords corresponding to keys of options.validators object passed to [MobxSchemaForm](https://alexhisen.gitbook.io/mobx-forms/mobx-schema-form/mobxschemaform) Validator functions have the call signature of [validateField](https://alexhisen.gitbook.io/mobx-forms/mobx-schema-form/validation)(). | In addition to built-in tv4 schema-based validation, you can specify an ordered list of custom validations that will be called if tv4 does not return a validation error. Validation stops after the first validation error. Each validator function should return either a validation error message string or a tv4-form error object (i.e. with code and optional message) that will be processed using validationMessage.                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| validationMessage                                     | String or Function or Object with tv4 numeric [error codes](https://github.com/geraintluff/tv4/blob/master/source/api.js) as keys (i.e. 302 for required) and "default" key (*Function,* *Object format and template parsing feature is not present in react-schema-form*)                                                          | [tv4](https://github.com/geraintluff/tv4) has built-in validation error messages but they are not very user-friendly. You can optionally specify the validation error messages to be used on each field on a per-tv4-error-code basis plus a catch-all "default" message in this object. The messages themselves are parsed as a template with [lodash.template](https://lodash.com/docs/#template) in whatever format you have configured in your app with [lodash templateSettings](https://lodash.com/docs/#templateSettings). Instead of a template string, you can also use a function, which willreceive the same [context](#templatecontext) object as thelodash template, and should return an error message. Messages defined here will also be used to process tv4-format error objects in model.dataErrors and objects returned by custom validations. |
| className (\*)                                        | String                                                                                                                                                                                                                                                                                                                              | CSS class name(s) to place into the optional [FieldWrapper](https://alexhisen.gitbook.io/mobx-forms/widget-types#fieldwrapper) or fieldset. Note that to place a custom class name on the React-Toolbox widget itself you need to put it in props.className instead.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| items                                                 | Array                                                                                                                                                                                                                                                                                                                               | Currently only supported on a fieldset. Contains an ordered list of Objects in Form Metadata Format and allows you to place certain fields inside a fieldset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| condition                                             | String                                                                                                                                                                                                                                                                                                                              | If provided, and when it eval()s to (strictly) false, the field will not be mounted. You can reference *model* (i.e. model.data.myProperty) variable as pased to MobxSchemaForm , plus the variable *form* will contain the [formShape](https://github.com/alexhisen/mobx-schema-form/blob/master/src/schemaFormPropTypes.js#L6) object for this field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| falseConditionValue (\*\*)                            | Any                                                                                                                                                                                                                                                                                                                                 | If not undefined, when condition eval() *changes* to (strictly) false, the corresponding model data property will be set to this value. Typically this would be null. The corresponding model dataErrors property will also be nulled (regardless of falseConditionValue).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| mobxCondition (\*)                                    | String                                                                                                                                                                                                                                                                                                                              | Works exactly the same way as condition but is eval()ed inside asSchemaField. It's mostly historical now - there shouldn't be any difference between condition and mobxCondition any more. Regular condition is always eval()ed first.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| requiredCondition (1.10+)                             | String                                                                                                                                                                                                                                                                                                                              | If provided, and when it eval()s to true, the field will be considered required. The field should not be included in the required array when using this. Eval()ed in the same context as condition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| readOnly (1.11+)                                      | Boolean                                                                                                                                                                                                                                                                                                                             | If true, the field will always be readOnly/disabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| readOnlyCondition (1.14.1+)                           | String                                                                                                                                                                                                                                                                                                                              | If provided, and when it eval()s to true, the field will be considered readOnly/disabled. Overrides the readOnly property if present. Eval()ed in the same context as condition.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |

> \* = feature not present in react-schema-form. \*\* = new feature in v1.5. \*\*\* = new feature in v1.9.

## validationMessage template context <a href="#templatecontext" id="templatecontext"></a>

| property / template variable                                             | Description                                                                                                                                                                                                                                                                    |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| code                                                                     | [Numeric Error Code returned by tv4](https://github.com/geraintluff/tv4/blob/master/source/api.js) or "default"                                                                                                                                                                |
| error                                                                    | Error object returned by tv4.validate(), with a message property containing the error message string it generated.                                                                                                                                                             |
| value                                                                    | The value being validated.                                                                                                                                                                                                                                                     |
| model                                                                    | Instance of FormStore or [modelShape](https://github.com/alexhisen/mobx-schema-form/blob/master/src/schemaFormPropTypes.js#L51) object.                                                                                                                                        |
| All fields from the formField object, i.e. title, minimum, maximum, etc. | All fields from a [formShape](https://github.com/alexhisen/mobx-schema-form/blob/master/src/schemaFormPropTypes.js#L6) object (specially merged Form Field Metadata and [Data Property Schema](https://alexhisen.gitbook.io/mobx-forms/mobx-schema-form/data-property-schema)) |
