use-form-state

use-form-state

_{Built with ❤︎ by Wappla and contributors}

Table of Contents

• Getting Started
• Examples
  • Basic Usage
• API
  • useFormState
    • initialValues
    • formOptions
      • formOptions.validation
      • formOptions.validationOptions
      • formOptions.valuesToInput
      • formOptions.debug
    • values
    • errors
    • isDirty
    • isValid
    • isPristine
    • setValues
    • handleChange
    • handleNativeChange
    • validate
    • updateErrors
    • resetForm
    • getInputProps
    • getNativeInputProps
    • valuesToInput
    • getValue
    • getErrorMessages
    • hasError
  • createFormValidation
    • path
    • validate
      • validate.currentValue
      • validate.allValues
      • validate.validationOptions
    • message
• Contributing
• Versioning
• Authors
• About us
• License

Getting Started

To get it started, add use-form-state to your project:

npm install --save use-form-state

Please note that use-form-state requires react@^16.12.0 as a peer dependency.

Examples

Basic Usage

import useFormState from 'use-form-state'

export const LoginForm = ({ onSubmit }) => {
    const { getNativeInputProps } = useFormState()

    return (
        <form onSubmit={onSubmit}>
            <input {...getNativeInputProps('email')} required />
            <input {...getNativeInputProps('password')} required />
        </form>
    )
}

From the example above, as the user submits the form, the formState object will look something like this:

{
    values: {
        email: '[e-mail]',
        password: '123456789',
    },
    errors: [],
    isDirty: true
    isValid: true,
    isPristine: false,
    setValues: Function,
    handleChange: Function,
    handleNativeChange: Function,
    validate: Function,
    updateErrors: Function,
    resetForm: Function,
    getInputProps: Function,
    getNativeInputProps: Function,
    valuesToInput: Function,
    getValue: Function,
    getErrorMessages: Function,
    hasError: Function,
}

API

useFormState

import useFormState from 'use-form-state'

export const FormComponent = () => {
    const {
        values,
        errors,
        isDirty,
        isValid,
        isPristine,
        setValues,
        handleChange,
        handleNativeChange,
        validate,
        updateErrors,
        resetForm,
        getInputProps,
        getNativeInputProps,
        valuesToInput,
        getValue,
        getErrorMessages,
        hasError,
    } = useFormState(initialValues, formOptions)
    return (
        // ...
    )
}

initialValues

useFormState takes an optional initial values object with keys as the name property of the form inputs, and values as the initial values of those inputs.

formOptions

useFormState also accepts an optional form options object as a second argument with following properties:

formOptions.validation

Function that returns an array of validators created by createFormValidation

Example: See return value of createFormValidation

Default: empty array

formOptions.validationOptions

Adds extra options that can be used in the validation. See validate.validationOptions for more info

Example:

const isCompany = user.type === 'company'

const formState = useFormState(initialValues, {
    validationOptions: {
        isCompany,
    }
})

Default: empty object

formOptions.valuesToInput

Function that can be used to manipulate the values used in the form state before submitting the form. This can be useful when the name of the input field differs from the API or when you need to parse/format dates for example.

Example:

const formState = useFormState(initialValues, {
    valuesToInput: ({
        firstName,
        birthDate,
        ...otherValues,
    }) => ({
        ...otherValues,
        first_name: firstName,
        birth_date: birthDate.toISOString(),
    })
})

Default: values from state

formOptions.debug

When set to true, useFormState will log its state to the console when changes are made.

Default: false

values

errors

isDirty

isValid

isPristine

setValues

handleChange

handleNativeChange

validate

updateErrors

resetForm

getInputProps

getNativeInputProps

valuesToInput

getValue

getErrorMessages

hasError

createFormValidation

import useFormState, { createFormValidation } from 'use-form-state'

export const FormComponent = () => {
    const formState = useFormState(initialValues, {
        validation: createFormValidation([{
            path: 'firstName',
            validate: (name) => name !== '',
            message: 'First name is required!',
        }, {
            path: 'birthDate',
            validate: (date) => date > new Date(),
            message: 'Date must be after now.',
        }, {
            path: 'vatNumber',
            validate: (vatNumber, values, { isCompany }) => (
                isCompany && vatNumber !== ''
            ),
            message: 'VAT number is required for a company.',
        }])
    })
    return (
        // ...
    )
}

path

Required

path references the name to the value in the formState where you want to add the validation on.

validate

Required

Function that validates the given value and returns the result of the expresion.

validate.currentValue

The first argument of validate is the value from the formState based on the given path.

validate.allValues

Second argument includes all the values from the formState.

validate.validationOptions

validationOptions is an optional argument you can use as external "dependency" for your validation expression.

message

The message you want to display near the form input to show the user what went wrong.

Default: 'Invalid'

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• Sander Peeters - Initial work - Sander Peeters

See also the list of contributors who participated in this project.

About us

Wappla BVBA We shape, build and grow ambitious digital products.

License

This project is licensed under the MIT License - see the LICENSE.md file for details