React Form CTRL

A declarative form controller and validator for ReactJS.

Bundle size: 6.9 KB gzipped

Features

• No schema
• Declarative
• Extremely reusable forms
• Field level reusability
• Built-in and custom validators
• Controlled inputs
• With decorators

1. Getting started

npm install --save react-formctrl

1.1. Wrap all your application with:

export function App(props) {
    return (
        <FormProvider>
            {'... your app ...'}
        </FormProvider>
    )
}

1.2. Create and decorate your field component:

let InputField = ({label, placeholder, name, type, required, onChange, onBlur, value}) => {

    const getLabel = () => {
        return required ? `${label}*` : label
    }

    return (
        <div>
            <label for={name}>{getLabel()}</label>
            <input id={name} name={name} 
                type={type} 
                onChange={onChange} 
                onBlur={onBlur}
                placeholder={placeholder || label}
                value={value} 
            />
        </div>
    );
}
InputField = controlledField()(InputField)

Now, your field component will need two required props:

• form: the name of the form that the field is attached to;
• name: the name of the field;

And will have some optional properties too:

• type: The input field type.
• required: true if the input field is required.
• pattern: The regex to validate the field pattern.
• integer: true if when the Field type property is "number" and should validate to integer value.
• match: Another field name that the value of this field should match.
• min: The min number value of a field with type "number".
• max: The max number value of a field with type "number".
• minLength: The min string value length of a field.
• maxLength: The max string value length of a field.

The controlledField decorator will inject a ctrl property which can be used to access the field state:

• valid/invalid: The field validation state;
• pristine/dirty: The field modification state;
• untouched/touched: The field access state (changed on blur);
• unchanged/changed: The field change state (initial value comparison);
• errors: An array of the validation errors: ([{key: 'email', params: {value: 'email@'}}]);

The controlledField decorator automatically handles the value, onChange and onBlur properties, so you just need to bind them to a input.

1.3. Build and decorate your forms:

let PersonForm = ({form, formCtrl, onSubmit, person = {}}) => (
    <Form name={form} onSubmit={onSubmit}>
        <div class="fieldset">
            <div class="fields-container">
                <InputField 
                    form={form} 
                    name="name" 
                    label="Name" 
                    initialValue={person.name} 
                    required 
                />
                <InputField 
                    form={form} 
                    name="email" 
                    type="email" 
                    label="E-mail" 
                    initialValue={person.email} 
                    required 
                />
            </div>
            <div class="buttons-container">
                <button type="submit" disabled={formCtrl.invalid || formCtrl.unchanged}>Save</button>
                <button type="reset" disabled={formCtrl.unchanged}>Reset</button>
            </div>
        </div>
    </Form>
)
PersonForm = controlledForm()(PersonForm)

Now, your field component will need a required props:

• form: the name of the form that the controller will be attached to;

The controlledForm decorator will inject a formCtrl property which can be used to access the form state:

• valid/invalid: The form's fields validation state;
• pristine/dirty: The form's fields modification state;
• untouched/touched: The form's fields access state (changed on blur);
• unchanged/changed: The form's fields change state (initial value comparison);
• values: The values of the form ({[fieldName]: 'fieldValue'});
• files: the selected files of the form ({[fieldName]: File[]});

If you need to programatically change a field's value, use: formCtrl.setFieldValue('fieldName', 'newValue'). Just be careful about the phase that you trigger the change, because this will trigger the Form and related Field update phase. So, ensure the form component update effects don't triggers setFieldValue again infinitely.

1.4. Finally, use and reuse your forms!

function CreatePersonRoute() {
    return <PersonForm form="createPersonForm" />
}

function EditPersonRoute() {
    const person = {
        name: 'Leandro Hinckel Silveira',
        email: '[e-mail]'
    }
    return <PersonForm form="editPersonForm" person={person} />
}

2. Adding custom validation

2.1. Create a class that extends CustomValidator

class NoStupidPassword extends CustomValidator {
    constructor() {
        super('stupidpass')
    }
    validate(formCtrl, props, value, files) {
        return !/^123456789$/i.test(value)
    }
}

The string parameter of super constructor determines the key name of the validator to use it later.

2.2 Declare it on FormProvider component

function App() {
    return (
        <FormProvider validators={[new NoStupidPassword()]}>
            <UserForm form="userForm">
        </FormProvider>
    )
}

2.3 Then activate the validator

Use the validator's key name passed to the super constructor to activate the validation:

let UserForm = ({form, formCtrlm onSubmit}) => (
    <Form name={form} onSubmit={onSubmit}>
        <InputField 
            form={form} 
            name="username" 
            label="Username" 
            required 
        />
        <InputField 
            form={form} 
            name="password" 
            type="password" 
            label="Password" 
            validate="stupidpass"
            required 
        />
        <InputField 
            form={form} 
            name="confirmPassword"
            type="password"
            label="Confirm password"
            match="password"
            validate="stupidpass"
            required 
        />
        <button type="submit" disabled={formCtrl.invalid || formCtrl.unchanged}>Save</button>
    </Form>
)
UserForm = controlledForm()(UserForm)

3. Reach field level reusability

The field level reusability means that even the specific forms fields can be reusable thanks to Form and Field decoupling.

3.1 Create form's part components

function UserInformationsFields({form, user = {}}) {
    return (
        <div>
            <InputField 
                form={form} 
                name="name" 
                label="Full name" 
                initialValue={user.name} 
            />
            <InputField 
                form={form} 
                name="email" 
                type="email" 
                label="E-mail" 
                initialValue={user.email} 
            />
            <InputField 
                form={form} 
                name="confirmEmail" 
                type="email" 
                label="Confirm e-mail" 
                initialValue={user.email} 
                match="email"
            />
        </div>
    )
}
function UserCredentialsFields({form, user = {}}) {
    return (
        <div>
            <InputField 
                form={form} 
                name="username" 
                label="Username" 
                initialValue={user.username} 
                required
                minLength={6}
                maxLength={18}
            />
            <InputField 
                form={form} 
                name="password" 
                type="password" 
                label="Password" 
            />
            <InputField 
                form={form} 
                name="confirmPassword" 
                type="password" 
                label="Confirm password" 
                match="password"
            />
        </div>
    )
} 

3.2 Reuse them in different forms

let QuickUserRegistrationForm = ({form, formCtrl, onSubmit}) => (
    <Form name={form} onSubmit={onSubmit}>
        <UserCredentialsFields form={form} />
        <button type="submit" disabled={formCtrl.invalid || formCtrl.unchanged}>Save</button>
    </Form>
)
let FullUserForm = ({form, formCtrl, onSubmit, user = {}}) => (
    <Form name={form} onSubmit={onSubmit}>
        <UserInformationsFields form={form} user={user} />
        <UserCredentialsFields form={form} user={user} />
        <button type="submit" disabled={formCtrl.invalid || formCtrl.unchanged}>Save</button>
    </Form>
)
QuickUserRegistrationForm = controlledForm(QuickUserRegistrationForm)
FullUserForm = controlledForm(FullUserForm)

Full documentation

FormProvider

The component that controls all form values and events. There may only be one instance of this component in the application.

Properties

Name	Type	Default value	Description
validators	Validator[]	[]	An array of custom validators.

Form

The component responsible for form's registration and submit handlers.

Properties

Name	Type	Default value	Description
name	string		The form id and name
className	string		The CSS classes for the native form component rendered by this component
onSubmit	Function		A submit handler function which receives the form values object by parameter: (formValues) => doSomething(formValues)
onReset	Function		A reset event handler function: () => doSomething()

FormControl

Component responsible for injecting the controller of a form into a child component.

Properties

Name	Type	Default value	Description
form	string		The name of a registered form (or to be registered later by an Form component)
onChange	Function		A change event handler function which receives the form controller by parameter: (formCtrl) => doSomething(formCtrl)
inject	Function		A function responsible for transforming the form controller into an object containing as key the name of the property to be injected and the value of the property: (formCtrl) => ({injectedFormNameProp: formCtrl.formName})

Injects

Name	Type	Description
formCtrl	FormStateController	The form controller

FormStateController

Name	Type	Description
formName	string	The name of the watched form.
valid	boolean	true if the form is valid.
invalid	boolean	true if the form is invalid.
untouched	boolean	true if all fields of the form are untouched (field blur).
touched	boolean	true if any field of the form was touched (field blur).
pristine	boolean	true if all fields of the form never changed it's value since it's loaded or reseted.
dirty	boolean	true if any field of the form has changed it's value one or more times since it's loaded or reseted.
unchanged	boolean	true if all fields values of the form are exactly equals it's initial values.
changed	boolean	true if any field value of the form aren't exactly equals it's initial value.
values	object{string: string}	The fields values of the form: {[fieldName]: [fieldValue]}.
files	object{string: File[]}	The selected files of each file field of the form.
fields	object{string: FieldStateController}	The fields controllers of the form: {[fieldName]: [fieldCtrl]}
setFieldValue	Function	Method to programmatically change a field value: props.formCtrl.setFieldValue('fieldName', 'newValue').
reset	Function	Method to programmatically reset all form instances with this form name: props.formCtrl.reset().

Field

Component that injects an form's field control properties to it's child.

Properties

Name	Type	Default value	Description
name	string		The name of the field.
form	string		The name of the field's form.
className	string		The CSS class to inject into it's component child.
required	boolean	false	true if the field is required.
pattern	string|RegExp		The regex to validate the field value.
type	string	text	The input field type. Supports all types, but currently only the "email" and "number" types has out of the box validation.
integer	boolean	false	true if when the Field type property is "number" and should validate to integer value.
match	string		Another field name that the value of this field should match.
min	number|string		The min number value of a field with type "number".
max	number|string		The max number value of a field with type "number".
minLength	number|string		The min string value length of a field.
maxLength	number|string		The max string value length of a field.
initialValue	Date|number|string	The field's initial value.
inject	Function		A function responsible for transforming the Field component injection properties into an object containing as key the name of the property to be injected and the value of the property: (field) => ({injectedOnChange: field.onChange})
onChange	Function	Field change event handler called after "react-formctrl" state change cycle. (fieldCtrl) => foo(fieldCtrl)
onBlur	Function	Field blur event handler called after "react-formctrl" state change cycle. (fieldCtrl) => foo(fieldCtrl)
onReset	Function	Handler called when the form that this field is attached is reseted. (fieldCtrl) => foo(fieldCtrl)

Injects

Name	Type	Description
name	string	The name of the field.
form	string	The name of the field's form.
className	string	The CSS class to inject into it's component child.
required	boolean	false
pattern	string|RegExp	The regex to validate the field value.
type	string	The input field type.
onChange	HTMLEventHandler	The field change event handler: (e) => handleChange(e.target.value).
onBlur	HTMLEventHandler	The field blur event handler: (e) => handleBlur(e.target.name).
value	string	The current field value.
files	File[]	The selected files of the field.
ctrl	FieldStateController	The field controller.

FieldStateController

Name	Type	Description
valid	boolean	true if the field is valid.
invalid	boolean	true if the field is invalid.
untouched	boolean	true if the field is untouched (field blur).
touched	boolean	true if the field was touched (field blur).
pristine	boolean	true if the field never changed it's value since it's loaded or reseted.
dirty	boolean	true if the field has changed it's value one or more times since it's loaded or reseted.
unchanged	boolean	true if the field value is exactly equals it's initial value.
changed	boolean	true if the field value isn't exactly equals it's initial value.
value	string	The value of the field.
files	File[]	The field selected files.
errors	ValidationError[]	An array of strings with all current validation errors of the field.
props	FieldStateProperties	Some properties of the Field.

FieldStateProperties

Name	Type	Description
type	string	The input field type.
required	boolean	true if the input field is required.
pattern	string|RegExp	The regex to validate the field pattern.
integer	boolean	true if when the Field type property is "number" and should validate to integer value.
match	string	Another field name that the value of this field should match.
min	number|string	The min number value of a field with type "number".
max	number|string	The max number value of a field with type "number".
minLength	number|string	The min string value length of a field.
maxLength	number|string	The max string value length of a field.
initialValue	Date|number|string	The field's initial value.

ValidationError

Name	Type	Description
key	string	Validation error message key.
params	object{string: any}	Validation error message parameters.