formcat

A simple and easy way to control forms in React using the React Context API

Programming language: JavaScript

License: MIT License

Tags: Code Design     Form Logic    

Latest version: v1.3.5

README

A simple and easy way to control forms in React using the React Context API

Getting Started

Install

With npm

npm install --save formcat

With yarn

yarn add formcat

How to use

First of all, we need to create a Field using the HOC withContextForm as the example below:

/* InputField.js */

import { withContextForm } from 'formcat'

const InputField = ({ error, ...input }) => (
  <input {...input} />
)

export default withContextForm(InputField)

Now we can use this component inside the Form:

import { Form } from 'formcat'
import InputField from './InputField'

function Main () {
  return (
    <Form>
      <InputField name="whatever" />
    </Form>
  )
}

API

Form

Props	Type	Default value	Description
keyUpValidation	Boolean	false	When true the validations Field works with keyUp
clearAfterSubmit	Boolean	false	When true the form will be reset after submit
onFormChange	Function	undefined	A callback that returns an object with name, type and value of the current change.
onSubmit	Function	undefined	A callback that returns an object with status and values.

Submit

For an easy submit process we can use the HOC withSubmit and create a Button that will be controlled by Form, or using the Submit component that already exists.

// Creating
import { withSubmit } from 'formcat'

const Submit = withSubmit(props => <button {...props} />)

//or

import { Submit } from 'formcat'

// Using

...
  render (
    <Form>
      ...
      <Submit> Button Text </Submit>
    </Form>
  )
...

Obs: This button will be enabled when Form is valid and disabled when is not valid

Custom Field

It's a field created with withContextForm.

Props	Type	Default value	Description
error	Boolean	false	A flag that controls the field validation
validations	Array	[]	A list with functions validation
required	Boolean	false	Set required validation for this field
defaultValue	String	""	Set initial text value
defaultChecked	String	""	Set initial checked for field

Using validations

We can use many validations per field using the props validations. All we need to do is create a pure function that returns true or false following the example below:

import { Form, withFormContext } from 'formcat'

const Field = withFormContext(({ error, ...input }) => (
  <input {...input} />
))


const Main = () => {

  // Validate if username is @guilouro
  const usernameValidation = value => (
    value === '@guilouro'
  )

  return (
    <Form>
      <Field
        name="username"
        validations={[usernameValidation]}
      />
    </Form>
  )
}

A validation function has two params value and state:

function validationName (value, state) {}

Param	Type	Description
value	String	Current field value
state	Object	An object with all fields value

Set values

We can set values out of Form using Ref and updateFieldValue as the example below:

Param	Type	Description
name	String	null
text	String	A new value for this field

import { Form, withFormContext } from 'formcat'

const Field = withFormContext(({ error, ...input }) => {}(
  <input {...input} />
))


const Main = () => {
  const form = useRef(null)

  const setValue = () => {
    form.current.updateFieldValue('username', '@guilouro')
  }

  return (
    <>
      <Form ref={ref}>
        <Field name="username" />
      </Form>

      <button onClick={setValue}>
        Set @guilouro as value
      </button>
    </>
  )
}

Fields we can use

There are some simple field created with withContexForm we can use in project or use as a reference for create a new custon field

InputField

A simple input field

import { InputField } from 'formcat/fields'

...
<InputField
  label="My Input"
  name="my-select"
/>
...

Param	Type	Default value	Description
name	String	null	Field name
label	String	''	A label for this field
type	String	text	A type for this input

Obs: And all common props

CheckboxField

A input checkbox field

import { CheckboxField } from 'formcat/fields'

...
<CheckboxField
  label="My Input"
  name="my-select"
/>
...

Param	Type	Default value	Description
name	String	null	Field name
label	String	''	A label for this field
defaultChecked	Boolean	false	A flag to define the initial status

Obs: And all common props

RadiosField

A simple input radio field

import { RadiosField } from 'formcat/fields'

...
<RadiosField
  label="My Select"
  name="my-select"
  options={[
    { label: 'Item 1', value: 1 },
    { label: 'Item 2', value: 2, checked: true }
  ]}
/>
...

Param	Type	Default value	Description
name	String	null	Field name
label	String	''	A label for this field
options	Array	[]	A list of objects with label, value and checked

Obs: And all common props

SelectField

A simple select field

import { SelectField } from 'formcat/fields'

...
<SelectField
  label="My Select"
  name="my-select"
  options={[
    { label: 'Item 1', value: 1 }
  ]}
/>
...

Param	Type	Default value	Description
name	String	null	Field name
label	String	''	A label for this field
options	Array	[]	A list of objects with label and value

Obs: And all common props

TextField

A simple textarea field

import { TextareaField } from 'formcat/fields'

...
<TextareaField
  label="My Text"
  name="my-text"
/>
...

Param	Type	Default value	Description
name	String	null	Field name
label	String	''	A label for this field

Obs: And all common props

Error styles

Invalid fields will receive a class: className="formcat-error"

Examples

Full form

A example with all fields, validation and a populate button

Creating a custom fields

A example of the how create a custom field

---

Contributing

If you want to contribute with this component: Contributing Documentation.