afreactforms

A library for simplified form management in React, built upon concepts of easy handling. Works with React(18.0.0+) and Next.js(12, 13.0+)

English | Русский

Motivation and Purpose of the Library

While working on yet another form development, using Formik or React-Hook-Forms, I couldn't find a convenient tool that was also elegant and simple to use.

This led to the creation of afreactforms, which aims to address these issues.

For validation, it uses **yup**.

Installation

Regular library installation via npm:

npm install afreactforms

Import is as follows:

import {useForm, Form, Field, FieldError} from "afreactforms";

Usage

Setting up and using is extremely simple. Let's say we have a form with email and password.

We need to use the useForm hook, which takes an object as follows:

{ 
    initialValues: {
        [inputName]: either an empty string "", or "some text"
    }
    validationSchema: yup validation schema
}

This gives:

const SignupSchema = Yup.object().shape({your validation});

const {values, errors, serverError, touches, setServerError, service} = 
    useForm({initialValues: {email: '', password: ''}, validationSchema: SignupSchema});

Outputs are:

Name	Description
values	Object with inputs {[name]: input string}
errors	Object with errors {[name]: error string}
serverError	String with server error, see [Go to the errors section]
touches	Object with input focus indicator {[name]: boolean value}
setServerError	Function to update the server error state
service	Object for library form functionality. DO NOT USE OUTSIDE < Form />

Using the Form

Next, you need a form as follows:

import {useForm, Form, Field, FieldError} from "afreactforms";

function Component(){
    //use the useForm hook
    const {values, errors, serverError, touches, setServerError, service} = useForm({
        initialValues: {
            email: '',
            password: '',
            name: '',
        }, validationSchema: SignupSchema
    });

    //render the element
    return (
        <Form
            //You can provide a class
            className={'flex flex-col gap-1'}
            //You must provide a submit function
            onSubmit={() => {
                fetch('Server request with form').then(
                    result => ...,
                error  => setServerError("Some error!")
            )
            }}
            //MUST PASS THIS PROP
            serviceProp={service}
        >
            //Fill with any nodes
            <p>Registration</p>
            //!For library input fields, you need to provide the name - from initialValues
            <Field
                //Mandatory - name from initialValues
                name={'email'}
                //Mandatory - input type
                type={'email'}
                //Optional - classes
                className={'bg-red'}
                //Optional - placeholder
                placeholder={'Enter email'}
            />
            //Optional component for displaying validation errors
            //Provide name - from initialValues
            <FieldError name={'email'}>
                //You can use like this, with a function (errorMsg: string) => ReactNode;
                {errorMsg => {
                    return <a>{errorMsg}</a>
                }}
            </FieldError>

            <Field name={'password'} type={'password'}/>
            //Or simply provide an element that has an errorMsg prop inside
            <FieldError name={'password'}>
                //function MyErrorComponent({className, errorMsg}) {...}
                <MyErrorComponent />
            </FieldError>

            //Similarly, you can get server error*, by passing name - serverError
            //Without providing a component, it will return <p>Message</p>
            <FieldError name={'serverError'}
                //you can specify classes
                        className={'blue'}
            />
            //Regular button to submit the form
            <button type={"submit"}>Submit</button>
        </Form>
    )
}

That's it, now you have a form that will change, display errors, validation, and has automated functionality.

Main Components

Form

A wrapper component for your form, providing context for its children.

Component Props:

Name	Mandatory	Description
children	Yes	Form's child elements.
onSubmit	Yes	Form submit handler.
className	No	Class name for styling.
serviceProp	Yes	Form's service properties.

Usage:

<Form onSubmit={handleOnSubmit} serviceProp={service}>
    // child elements
</Form>

Field

Input field component that automatically synchronizes with the form context.

Component Props:

Name	Mandatory	Description
name	Yes	Field's name.
type	No	Input field type, e.g., "text", "email", etc.
placeholder	No	Input field placeholder.
className	No	Class name for styling.

Usage:

<Field name="email" type="email" placeholder="Insert your email" />

FieldError

Component to display field errors.

Component Props:

Name	Mandatory	Description
name	Yes	Name of the field to display error for. "serverError" - for server errors. gets serverError, set by setServerError("")
children	No	Custom component to display error or a function to render the error.
className	No	Class name for styling.

Usage:

//Without a node
<FieldError name="email" />
//With a function
<FieldError name="email">
    {(errorMsg) => <span style={{color: 'red'}}>{errorMsg}</span>}
</FieldError>
//With a component
//function MyErrorComponent({className, errorMsg}) {...}
<FieldError name="email">
    <CustomErrorComponent />
</FieldError>

useForm Hook

A hook to manage the form logic.

Hook Properties:

Name	Mandatory	Description
initialValues	Yes	Initial values for the form fields.
validationSchema	Yes	Validation schema for the fields using yup.

Usage:

const { values, errors, service } = useForm({ initialValues, validationSchema });

Return:

Name	Description
values	Object with inputs {[name]: input string}
errors	Object with errors {[name]: error string}
serverError	String with server error, see [Go to the errors section]
touches	Object with input focus indicator {[name]: boolean value}
setServerError	Function to update the server error state
service	Object for library form functionality. DO NOT USE OUTSIDE < Form />

License

MIT

Contacts

For issues or suggestions, use GitHub