Options

Introduction

Passing options to the createField() high-order component allows to control the behavior of the created field. That is extremely useful when implementing custom fields, or integrating third-party solutions to work with React Advanced Form.
You don't have to configure any of these options. Please use the defaults exposed with Field presets, unless you're customizing a field's behavior on purpose.

valuePropName

Type
string
Default value
"value"
Some fields update a prop different from the value upon the interaction with them. For example, a checkbox updates its checked prop. Provide the prop name to update on field's onChange using this option, in case it differs from value.
1
import React from 'react'
2
import { createField } from 'react-advanced-form'
3
4
const Checkbox = (props) => {
5
const { fieldProps } = props
6
return (<input {...fieldProps} />)
7
}
8
9
export default createField({
10
valuePropName: 'checked',
11
})(Checkbox)
Copied!

initialValue

Type
any
Default value
''
Initial value of all instances of a field. Useful for cases when the initial value of a field is different from an empty string.
1
export default createField({
2
/**
3
* Set initial value to the current date
4
* instead of an empty string (default).
5
*/
6
initialValue: Date.now(),
7
})(Datepicker)
Copied!
Note that initialValue is then mapped using mapValue option.

assertValue

Type
(params) => boolean
Default value
({ value }) => !!value
A predicate function stating that a field contains some value.
Useful for describing a proper validation behavior for a custom field where its value is represented using a complex instance (i.e. Object).
1
export default createField({
2
valuePropName: 'range',
3
mapValue: (value) => ({
4
from: value[0],
5
to: value[1],
6
}),
7
assertValue: (range) => {
8
return range.from || range.to
9
},
10
})(RangeInput)
Copied!
In the example above, we have created a field that accepts an array of integers as its value, and transforms it into the { from, to } Object to be stored in the field's state. In order to have a proper validation logic, such as validation on mount, we need to supply a custom predicate that describes when our field has some actual value.

mapValue

Type
any
Default value
(value) => value
Maps a "raw" field's value into its representative in the field's state.
1
import { createField } from 'react-advanced-form'
2
3
export default createField({
4
mapValue: (value) => {
5
return dateFns.parse(value)
6
},
7
})(Datepicker)
Copied!
This only affects external value updates (i.e. receiving next value prop, resetting or clearing a field). This has no effect when the native onChange callback is dispatched.

allowMultiple

Type
boolean
Default value
false
Allows multiple instances of a field with the same name within a single form's scope. This affects both form and Field group scopes.
By default, field's name is the unique identifier that prevents the registration of duplicate fields. However, some field types (i.e. radio button, or your custom field) may want to render multiple field components with the same name.

mapPropsToField

Definition

Type
(params) => Object
Default value
({ fieldRecord }) => fieldRecord

Parameters

Param name
Type
Description
valuePropName
string
Value prop name of a field.
props
Object
Raw field component's props.
fieldRecord
Object
Reference to the field's record in the form's state.
context
Object
Each field has its record stored in the internal state of the Form component. That record is composed based on the field's props, but may (and sometimes must) be altered to provide proper field functionality.
1
import React from 'react'
2
import { createField } from 'react-advanced-form'
3
4
const Checkbox = (props) => {
5
const { fieldProps } = props
6
return (<input {...fieldProps} />)
7
}
8
9
export default createField({
10
valuePropName: 'checked',
11
mapPropsToField: ({ fieldRecord }) => ({
12
...fieldRecord,
13
type: 'checkbox',
14
initialValue: props.checked,
15
}),
16
})(Checkbox)
Copied!

enforceProps

Definition

Type
(params) => Object
Default value
() => ({})

Parameters

Param name
Type
Description
props
string
Raw field component's props.
contextProps
Object
Field record in a form's state.
Allows enforcing an Object of props which will override the Field's registration record within the form.
1
import React from 'react'
2
import { createField } from 'react-advanced-form'
3
4
const Checkbox = (props) => {
5
const { fieldProps } = props
6
return (<input {...fieldProps} />)
7
}
8
9
export default createField({
10
valuePropName: 'checked',
11
enforceProps: ({ contextProps }) => ({
12
checked: contextProps.checked,
13
}),
14
})(Checkbox)
Copied!

beforeRegister

Definition

Type
(params) => Object
Default value
({ fieldProps }) => fieldProps

Parameters

Param name
Type
Description
fieldProps
string
Original field props.
fields
Object
Reference to all fields.
Applies additional transformation or logic to the field right before it is registered. Allows to completely prevent field registration when false is returned from this method.

Modifying field's record

1
export default createField({
2
beforeRegister: ({ fieldProps, fields }) => {
3
return {
4
...fieldProps,
5
/**
6
* Add a custom property "customProp"
7
* on the field's record in the state.
8
*/
9
customProp: 'foo',
10
}
11
}
12
})(FieldComponent)
Copied!

Preventing field registration

Returns false from beforeRegister method to prevent a field from registering its record in the parent form's state.
1
export default createField({
2
beforeRegister: ({ fieldProps, fields }) => {
3
const inputProps = fieldProps.getRef().props
4
5
/* Prevent field registration if it has "foo" prop */
6
if (inputProps.hasOwnProperty('foo')) {
7
return null
8
}
9
10
return fieldProps
11
}
12
})(FieldComponent)
Copied!

shouldValidateOnMount

Definition

Type
(params) => boolean
Default value
Determines whether a field should be validated upon mounting, if it has value (its assertValue resolves).

Parameters

Param name
Type
Description
[valuePropName]
any
Dynamic key that is value prop name, with value being a field's value.
valuePropName
string
Value prop name of a field.
fieldRecord
string
Reference to a field's record in a form's state.
context
Object
Determines whether a field should be validated upon mount.

serialize

Definition

Type
(params) => any
Default value
(value) => value

Parameters

Param name
Type
Description
value
any
Original serialized value of a field.
Returns the next serialization payload of a field.
Useful to provide transformations to a field's value upon form serialization.
1
export default createField({
2
/**
3
* Let's say we have a Datepicker component that
4
* stores his value as a DateFNS instance. We can
5
* format its value into a date string when
6
* the field is serialized.
7
*/
8
serialize(value) {
9
return dateFns.format(value, 'MM/DD/YYYY')
10
},
11
})(Datepicker)
Copied!
Note that serialize works complementary with Form.props.onSerialize, and it executed before the form's serialization transformer.