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.

import React from 'react'
import { createField } from 'react-advanced-form'
const Checkbox = (props) => {
const { fieldProps } = props
return (<input {...fieldProps} />)
}
export default createField({
valuePropName: 'checked',
})(Checkbox)

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.

export default createField({
/**
* Set initial value to the current date
* instead of an empty string (default).
*/
initialValue: Date.now(),
})(Datepicker)

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

export default createField({
valuePropName: 'range',
mapValue: (value) => ({
from: value[0],
to: value[1],
}),
assertValue: (range) => {
return range.from || range.to
},
})(RangeInput)

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.

import { createField } from 'react-advanced-form'
export default createField({
mapValue: (value) => {
return dateFns.parse(value)
},
})(Datepicker)

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.

import React from 'react'
import { createField } from 'react-advanced-form'
const Checkbox = (props) => {
const { fieldProps } = props
return (<input {...fieldProps} />)
}
export default createField({
valuePropName: 'checked',
mapPropsToField: ({ fieldRecord }) => ({
...fieldRecord,
type: 'checkbox',
initialValue: props.checked,
}),
})(Checkbox)

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.

import React from 'react'
import { createField } from 'react-advanced-form'
const Checkbox = (props) => {
const { fieldProps } = props
return (<input {...fieldProps} />)
}
export default createField({
valuePropName: 'checked',
enforceProps: ({ contextProps }) => ({
checked: contextProps.checked,
}),
})(Checkbox)

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

export default createField({
beforeRegister: ({ fieldProps, fields }) => {
return {
...fieldProps,
/**
* Add a custom property "customProp"
* on the field's record in the state.
*/
customProp: 'foo',
}
}
})(FieldComponent)

Preventing field registration

Returns false from beforeRegister method to prevent a field from registering its record in the parent form's state.

export default createField({
beforeRegister: ({ fieldProps, fields }) => {
const inputProps = fieldProps.getRef().props
/* Prevent field registration if it has "foo" prop */
if (inputProps.hasOwnProperty('foo')) {
return null
}
return fieldProps
}
})(FieldComponent)

shouldValidateOnMount

Definition

Type

(params) => boolean

Default value

assertValue

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.

export default createField({
/**
* Let's say we have a Datepicker component that
* stores his value as a DateFNS instance. We can
* format its value into a date string when
* the field is serialized.
*/
serialize(value) {
return dateFns.format(value, 'MM/DD/YYYY')
},
})(Datepicker)

Note that serialize works complementary with Form.props.onSerialize, and it executed before the form's serialization transformer.