@4react / forms

Ready-to-use form context and validation for React Applications.

Usage

Import dependency

npm i @4react/forms

Compose fields

import { Form, FormField, FormData } from '@4react/forms'

const App = () => (
  <Form>
    <FormField name="username" accept={/^\w+$/}>
      {({ update, valid }) => <input ... />}
    </FormField>
    <FormField name="password">
      {({ update, valid }) => <input ... />}
    </FormField>
    <FormData>
      {({ values, valid }) => <button ... />}
    </FormData>
  </Form>
)

Live example

API

Form

Component that provides a context for a form.

import { Form } from '@4react/forms'

const App = () => (
  <Form>
    ...
  </Form>
)

| Name | Type | Default | Description | | --- | --- | --- | --- | | initialValues | object | - | optional - Initial values for the form fields. |

FormField

Component that registers a new field for the surrounding form.

import { FormField } from '@4react/forms'

...

<FormField name="email">
  {({ update, valid }) => (
    <input
      type="text"
      onChange={e => update(e.target.value)}
      style={{ borderColor: valid ? 'gray' : 'red' }}
    />
  )}
</FormField>

| Name | Type | Default | Description | | --- | --- | --- | --- | | name | string | - | Name of the field | | defaultValue | any | - | optional - Default value of the field. | | accept | Function, RegExp | - | optional - If provided, this function is used to validate the value of the field. For string fields (and compatible types fields) a RegExp can be use also. | | validateOn | "init", "update" | "update" | optional - Use to control which moments are take into consideration for validation. A list of values is also accepted. |

This components accept a child function, and provides to it an object with the following properties:

| Name | Type | Description | | --- | --- | --- | | update | Function | Required to update the value of the field. | | valid | boolean | Points if last validation is passed or none is executed yet. | value | any | The stored value of the field (for controlled inputs). |

FormData

Component that retrieves all values of the current form.

import { FormData } from '@4react/forms'

...
    
<FormData>
  {({ values, valid }) => (
    <button
      disabled={!valid}
      onClick={() => sendData(values)}
    >
      SEND DATA
    </button>
  )}
</FormData>

| Name | Type | Default | Description | | --- | --- | --- | --- | | validate | boolean | true | optional - Used for performance issues, setting this property to false will disable automatic validation. Manual validation can be triggered by calling the validate method passed to children. |

This components accept a child function, and provides to it the following properties:

| Name | Type | Description | | --- | --- | --- | | values | object | Object containing all values of the form. | | valid | boolean | Points if the values in all the fields are considered valid. Returns false if no validation is done yet. | validate | Function | For performance reasons it's possible to force validation only on demand. In these cases invoking this function will validate the entire form. |

Hooks

Alternatively to the use of the above components, it's possible to create custom fields and data consumers, using the following hooks:

useFormField

This hook will register a new field with the specified name, and returns the same set of properties of the FormField component (see FormField).

import { useFormField } form '@4react/forms'

const MyCustomField = ({ name }) => {
  const { update, valid } = useFormField(name)

  return <input ... />
}

| Name | Type | Default | Description | | --- | --- | --- | --- | | name | string | - | Name of the field. | | options | object | {} | optional - Object accepting all optional props of the FormField component (see FormField). |

useFormData

This hook retrieves collected values of the current form, and returns the same set of properties of the FormData component (see FormData).

import { useFormData } from '@4react/forms'

const MyCustomSubmit = () => {
  const { values, valid } = useFormData()

  return <button ... />
}

| Name | Type | Default | Description | | --- | --- | --- | --- | | options | object | {} | optional - Object accepting all optional props of the FormData component (see FormData). |