react-formctrl v1.4.3

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: 'leandro.hinckel@gmail.com'
    }
    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

Form

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

Properties

FormControl

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

Properties

Injects

FormStateController

Field

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

Properties

Injects

FieldStateController

FieldStateProperties

ValidationError