/formcat

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

Primary LanguageJavaScriptMIT LicenseMIT

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

Build Status codecov.io styled with prettier

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 'react-contex-form'
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

Edit Formcat

Creating a custom fields

A example of the how create a custom field

Edit Creating custom fields


Contributing

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