React Contextual Forms

Simple forms for React using context.

Features

• Easy to use
• Bring your own components
• Write your own validators
• Made with TypeScript (available types)

Installation

This package uses hooks so it requires at least version 16.8 of React.

npm install react-contextual-forms

Usage

After installing the package from NPM you can start using the 3 available components (Form, Field and Interaction) to build your forms.

Components

Form

The 'Form' component is the one that will provide the context for the others, you can place 'Field' and 'Interaction' components within it. There is no restriction on the number of forms you can use next to each other, how many you use or where you place the fields/interactions in the form.

Prop	Type	Required	Description
onChange	function	no	Event that triggers when the form changes
onSubmit	function	yes	Submit event for the form

Field

A 'Field' component only serves as a wrapper for the actual component and provides it with a number of props, how you want to display the field is completely up to you.

Prop	Type	Required	Description
component	FunctionComponent< IFieldComponentProps >	yes	The component to render as the field
defaultValue	string	no	The default value of the field
id	string	yes	ID of this field
onChange	function	no	Returns the value of the field when it changes
props	object	no	Props of the field which are passed down to the component
validators	Array< IFieldValidator >	no	Collection of all validator functions

IFieldComponentProps

Name	Type	Description
error	string / null	The error message for the field if there is a validation error, else null
isTouched	boolean	Has the field been touched by the user or not
props	object	Passed down props from the field
value	string	The current value of the field
update	function	[(value: string) => void] Function to update the field value

IFieldValidator

Name	Type	Description
check	function	[(value: string) => boolean] Function to validate the field, must return boolean
message	string	The error message to show if the validation fails

Interaction

If you find the need to update a form value directly, you can use an 'Interaction' component. Note that these only work when they are located within a Form component.

Prop	Type	Required	Description
component	FunctionComponent< IInteractionComponentProps >	yes	The component to render as the interaction
props	object	no	Props of the interaction which are passed down to the component

IInteractionComponentProps

Name	Type	Description
props	object	Passed down props from the intercaction
update	function	[(id: string, value: string) => void] Function to update field's value

Examples

Javascript

import React from 'react'
import { Form, Field, Interaction } from 'react-contextual-forms'

const formValidators = {
    required: {
        check: (value) => {  
            if (!value) return false
            return true
        },
        message: 'This field is required'
    }
}

const Input = ({ error, isTouched, value, update }) => {
    return (
        <span>
            <input type="text" value={value} onChange={(e) => update(e.target.value)} />
            <p>{(error && isTouched) && error}</p>
        </span>
    )
}

const Select = ({ error, isTouched, value, update }) => {
    return (
        <span>
            <select value={value} onChange={(e) => update(e.target.value)}>
                <option>A</option>
                <option>B</option>
                <option>C</option>
            </select>
            <p>{(error && isTouched) && error}</p>
        </span>
    )
}

const ChangeButton = ({ update }) => {
    return (
        <button 
            type="button" 
            onClick={() => { 
                update('lastname', 'Doe')
                update('firstname', 'John')
            }}
        >Change</button>
    )
}

function App() {
    return (
        <div className="App">
            <p>FORM</p>
            <Form onSubmit={(form) => console.log(form)}>
                <div>
                    <Field id="lastname" validators={[formValidators.required]} component={Input} />
                    <Field id="firstname" validators={[formValidators.required]} component={Input} />
                </div>
                <div>
                    <Field id="choice" defaultValue="B" component={Select} />
                </div>
                <Interaction component={ChangeButton} />
                <button type="submit">Submit</button>
            </Form>
        </div>
    )
}

Typescript

import React from 'react'
import { Form, Field, Interaction, IFieldComponentProps } from 'react-contextual-forms'

const formValidators = {
    required: {
        check: (value) => {  
            if (!value) return false
            return true
        },
        message: 'This field is required'
    }
}

const Input: React.FunctionComponent<IFieldComponentProps> = ({ error, isTouched, props, value, update }) => {
    return (
        <span>
            <label>{props?.label}</label>
            <input type="text" value={value} onChange={(e) => update(e.target.value)} />
            <p>{(error && isTouched) && error}</p>
        </span>
    )
}

function App() {
    return (
        <div className="App">
            <p>FORM</p>
            <Form onChange={(form) => console.log('CHANGE', form)} onSubmit={(form) => console.log('SUBMIT', form)}>
                <div>
                    <Field id="lastname" validators={[formValidators.required]} component={Input} props={{ label: 'Last name' }} />
                    <Field id="firstname" validators={[formValidators.required]} component={Input} />
                </div>
                <button type="submit">Submit</button>
            </Form>
        </div>
    )
}

License

MIT