react-form

Fast and easy way to create form in React

Installation

Using npm

npm install @oladimillion/react-form

Using yarn

yarn add @oladimillion/react-form

Basic Usage

Example

import { Form, Field, SubmitButton } from '@oladimillion/react-form'


const validationRules = {
  text: {
    validation: ['required'],
    message: {
      required: 'This text field is required'
    }
  },
}

const initialValues = {
  text: 'react form',
}

const MyForm = () => {

  const onSubmit = async ({ values, errors, submitting, resetForm, setFormError, setFormValue }) => {
    // perform async action here
  }

  return (
    <Form 
      onSubmit={onSubmit}
      validationRules={validationRules}
      initialValues={initialValues}
    >
      <Field type='text' label='Text Field' name='text' placeholder='Text field' />
      ...
      <SubmitButton>Save</SubmitButton>
    </Form>
  )
}

API

• Form
• Field
• FieldArray
• useField
• useFormContext

<Form />

Form handles the form's validation, change and submit events.

    <Form 
      onSubmit={onSubmit}
      validationRules={validationRules}
      initialValues={initialValues}
      readOnly={false}
    >
      ...
    </Form>

Form props

• onSubmit(Object: { values: object, errors: objects, submitting: boolean, resetForm: function, setFormError: function, setFormValue: function }) required

  Called when submit event is triggered.

  • values: object

    Key-value pair of field names and values.

  • errors: object

    Key-value pair of field names and errors.

  • submitting: boolean

    true when form is submitting.

  • setFormValue(values: object, useInitialValues: boolean): void

    Updates the form state with values.

  • setFormError(errors: object, useInitialErrors: boolean): void

    Updates the form state with errors.

  • resetForm(): void

    Resets the form state.

• validationRules: object

  Allows form fields custom validation.

  Validatorjs is used in the form validation.

    const validationRules = {
      email: {
        validation: 'required|email', // validation in string format
      }
    }
  
    const validationRules = {
      email: {
        validation: ['required', 'email'], // validation in array format
      }
    }
  
    // custom validation message
    const validationRules = {
      email: {
        validation: ['required', 'email'],
        message: {
          required: 'Email field is required',
          email: 'Email provided is invalid',
        }
      }
    }
  
    /* `depend` manages the dependency of a field on other fields */
    // depend as a function
    const validationRules = {
      email: {
        ...
        depend: (values, fieldName, fieldIndex) => {
          // `values` is the fields value in the form state
          // `fieldName` is the field name the depend is running against.
          // `fieldIndex` is the index of field in a field array. null for a non-array field.
  
          // perform your check here 
          // return a boolean value (true or false)
        }
      }
    }
  
    // depend as an object
    const validationRules = {
      email: {
        ...
        depend: { field1: 'value1', field2: 'value2' } // email is dependent on field1 and field2
      }
    }
  
    // depend as a string
    const validationRules = {
      email: {
        ...
        depend: 'field1' // email is dependent on field1
      }
    }
  
    // depend as a boolean
    const validationRules = {
      email: {
        ...
        depend: true // `false` will hide email field 
      }
    }

  Validation rule for a FieldArray using dot notation

    const validationRules = {
      fieldArray.*.email: {
        validation: ['required', 'email'],
      }
    }

• initialValues: object

  Defining initial value for form fields

• readOnly: boolean

  Form can be made read only by setting readOnly prop to true

<Field />

Field hooks up inputs to the form state using the name attribute.

    import { Field } from '@oladimillion/react-form'

    ...
    <Field type='password' label='Password' name='password' />
    ...

Field props

• name: string required

  Field name in the form state.

• type: string

  Input types, which can be text, textarea, select, checkbox, radio, switch, email, url, password, file, or number.

• placeholder: string

  Placeholder text for text, textarea, email, url, select, password and number input types.

• label: string

  Field label.

• renderLabel: function

  label can be customized using the renderLabel prop.

      <Field 
        renderLabel={() => <label>My label</label>}
        ...
      />

• renderErrorMessage(Object: { errors: array }): ReactComponent<array>

  Field's error messages can be customized using the renderErrorMessage prop.

      <Field 
        renderErrorMessage={({ errors }) => errors.map(error => <span>{error}</span>)}
        ...
      />

• options: array

  radio and select input types recieves options prop to render choices. options is a list of text: string and value: number|boolean|string object.

      // radio input type
      <Field 
        label='Radio Field'
        options={[{ text: 'Yes', value: 'yes' }, {text: 'No', value: 'no' }]} 
        type='radio' 
        name='radio'
      />

      // select input type
      <Field 
        label='Select Field'
        options={[{ text: 'Good', value: 3 }, { text: 'Better', value: 2 }, { text: 'Best', value: 1 }]} 
        type='select' 
        name='select2'
        placeholder='Placeholder Text'
      />

• as: ReactComponent

  Input fields are rendered using Semantic UI React components. But with as prop, custom input field can be rendered instead.

      const TextArea = (props) => <textarea {...props} row={3} placeholder='description...' />
  
      <Field 
        label='Text area'
        name='textarea'
        as={TextArea}
      />

<FieldArray />

Groups of Field can be rendered using FieldArray.

Each Field in a FieldArray must have a name composed from the FieldArray name, field index and field name. eg. group.1.email

    import { Field, FieldArray } from '@oladimillion/react-form'

    ...
    <FieldArray name='fieldArray' label='Field Array'>
      {({ values, add, remove }) => (
        <FieldArray.Item mb={2}>
          {values.map((_, index) => (
            <FieldArray.Item key={index}>
              <FieldArray.RemoveButton onClick={() => remove(index)} />
              <Field type='textarea' label='TextArea Field' name={`fieldArray.${index}.textarea`} />
              <FieldArray.Divider />
            </FieldArray.Item>
          ))}
          <FieldArray.AddButton onClick={add} />
        </FieldArray.Item>
      )}
    </FieldArray>
    ...

FieldArray props

• name: string required

  FieldArray name in the form state.

• label: string

  FieldArray label.

• render(object: { value: array, add: function, remove: function }): ReactComponent

  values holds the items' value, add(value: any): void adds a new item to the array fields, and remove(index: integer): void removes an item from the array fields using its index.

    <FieldArray 
      ...
      render={({ values, add, remove }) => (...)}
    />

• children(object: { value: array, add: function, remove: function }): ReactComponent

  Same as render prop, but the function is passed as children.

    <FieldArray 
      ...
    >
      {({ values, add, remove }) => (...)}
    </FieldArray>

useField

useField is a custom react hook that let you hook up to the form state using the field name.

    import { useField, Form } from '@oladimillion/react-form'

    const CustomField = () => {
      const name = 'text'
      const { value, onChange, onBlur, required, readOnly } = useField(name)
      return (
        <div>
          <label>Field label</label>
          <input 
            value={value} 
            onChange={onChange} 
            onBlur={onBlur} 
            required={required} 
            disabled={readOnly} 
            name={name} 
            type='text' 
          />
        </div>
      )
    }

    const MyForm = () => {
      const onSubmit = () => {}

      return (
        <Form onSubmit={onSubmit}>
          <CustomField />
          ...
        </Form>
      )
    }

useField returned props

• value: any

  Field's value.

• error: array

  Field's validation error.

• onChange(e: ChangeEvent): void

  Change event handler.

• handleChange(e: ChangeEvent): void

  Change event handler.

• onBlur(e: BlurEvent): void

  Blur event handler.

• setValue(value: any): void

  Set the field's value.

• setError(error: string): void

  Set the field's error.

useFormContext

useFormContext is a custom react hook that let you hook up to the form state.

    import { useFormContext } from '@oladimillion/react-form'

    const formContext = useFormContext()

useFormContext returned props

• values: object

  Form fields' value.

• errors: object

  Form fields' validation error.

• handleSubmit(e: SubmitEvent): void

  Submit event handler.

• handleChange(e: ChangeEvent): void

  Change event handler.

• onBlur(e: BlurEvent): void

  Blur event handler.

• setFieldValue(fieldName: string, fieldValue: any): void

  Set the field's value.

• setFieldError(fieldName: string, fieldError: string): void

  Set the field's error.

• setSubmitting(submitting: boolean): void

  Set submitting to true or false.

• resetForm(): void

  Resets the form state.

• submitting: boolean

  true when form is submitting.

• dirty: boolean

  true when form is dirty.

• readOnly: boolean

  true when form is read only.

• setFormValue(values: object, useInitialValues: boolean): void

  Updates the form state with values.

• setFormError(errors: object, useInitialErrors: boolean): void

  Updates the form state with errors.

License

This project is licensed under the terms of the MIT license.