README

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.

Usage no npm install needed!