aphorm v0.2.1

Aphorm is a high performance React form component library.

Best used for:

• React webapps (supports v15+)
• Complex forms with lots of inputs
• Complex form data

Note:

• This library is under development, there's no strict versioning + documentation, and API may change anytime. Aka don't use unless you're desperate for speed (then go for v0.2.0)
• This is a basic component library with only plain state management and simple validation

Usage

Import:

import Aphorm from 'aphorm';

then

<Aphorm
    validateOnChange                              // default = false
    validateOnBlur                                // default = true
    validate={this.myValidationMethod}            // validation method
>
    // see below for all `aphormRenderProps`
    {aphormRenderProps => (
        fieldsList.map(field => (
            <div className="your-field-container">

                // render the field's input control with `renderField`
                {aphormRenderProps.renderField({
                    id: field.id, // required - unique id to identify field
                    value: field.value, // initial value
                    // render a custom input component:
                    render: ({ value }) => (
                        <CustomInput
                            value={value}
                            onChange={(newValue) => (
                                aphormRenderProps.setFieldValue(field.id, newValue)
                            )}
                        />
                    ),
                    // or pass in a native HTML input type
                    type: field.type,
                })}

                // Optionally render the field's error message with `renderError`
                {aphormRenderProps.renderError({
                    id: field.id,
                    render: ({ errorMessage }) => (
                        <CustomError error={errorMessage} />
                    )
                })}
            </div>
        ))
    )}
</Aphorm>

or

<Aphorm render={this.renderFields} />

aphormRenderProps:

props that get passed into Aphorm.render and Aphorm.children

renderField(fieldData = {}):

fieldData is an object of key/value pairs that's passed into <input/> or your <CustomInput/>.

For native HTML inputs:

• Only id and type are required. onChange is handled internally by <Aphorm>.

• Accepts anything the native HTML input accepts

For custom inputs:

• Only id and render are required.

  • render({ value }): return your <CustomInput> component that handles its own input events (onChange, onBlur, etc.).

  • proxy your component's input events to update <Aphorm>'s state with setFieldValue(field.id, newFieldValue)

renderError(fieldData = {})

Similar to renderField except here's where you render the field's error.

Required:

• Only the field's id is required
• You'll probably want to render your own error component though (by default the errorMessage is just rendered next to the field's input)
  • render({ errorMessage }): render your <CustomError> component

getFormValues()

Returns a flat object of all of your form's values.

• key = unique field id
• value = field's value

setFieldValue(id = any, value = any)

Set a value for a specific field identified by the field's unique id.

Validation will run after the value has been set.

setValues(values = {})

Set values for multiple fields simultaneously. Pass in all the key/value pairs you want to update.

Don't worry if you have validateOnChange = true, validation will run just once.

setFieldError(id = any, errorMessage = '')

Set an errorMessage for a specific field identified by the field's unique id.

setErrors({ errorMessages = {} })

Set errorMessages for multiple fields simultaneously. Pass in all the key/value pairs you want to update.

errors()

Returns a flat object of all your form's errorMessages

• key = unique field id
• value = errorMessage

validateForm()

Trigger this to validate your form.

AphormProps

validateOnChange

Validate form onChange of any field's value. default = false

validateOnBlur

Validate form onBlur of any field's value. default = true

validate(formValues = {})

Method that gets triggered on <Aphorm/> validation. The form's values are passed in.

You need to return an object of errors

• key = unique field id
• value = error message string