amiable-forms

A library for creating forms in React using hooks. This project requires no dependencies other than React as a peer dependency and is written from the ground up with hooks in mind. It is easy to integrate into any form UI. To achieve this, no renderable form or field component are provided or required. Instead hooks are used to transform any component needed into a form. If desired, this allows forms to be created even without the use of standard browser form elements.

• built using React Hooks
• independent field handling
• highly compatible, easy to integrate
• efficient, fields only render when needed

Installation

amiable-forms requires React 16.8.3 or later.

npm install --save amiable-forms

Getting Started

First wrap the form components with the <AmiableForm> component provided by amiable-forms. This will not add any visual components or inject any props. Its purpose is only to provide a context for the hooks to use.

Field components can be defined with the useField hook. This can be done many different ways, a very simplistic version is shown in the example below.

The last hook that will most likely be required is the useSubmit hook which provides an onSubmit method.

const Input = props => {
  const { value, onChange } = useField({ name: props.name })
  return <input {...props} value={value} onChange={onChange} />
}

const SubmitButton = () => {
  const { onSubmit } = useSubmit()
  return <button onClick={onSubmit}>Login</button>
}

const process = values => console.log('Submit', values)

const LoginForm = () => (
  <AmiableForm process={process}>
    <Input name="username" placeholder="username" />
    <Input name="password" placeholder="password" type="password" />
    <SubmitButton />
  </AmiableForm>
)

To see a more complete example of a form built with amiable-forms use this codesandbox link: Simple Example Form
// TODO: update example to use 1.1.4

Documentation

AmiableForm

The AmiableForm component is used to provide a React context and is not a visual component. This shouldn't be confused with any visual UI Form components that might be required for your specific form setup. The AmiableForm component must be wrapped around the entire form for any of the amiable-forms hooks and helper components to function. This allows form state to be shared without needing explicit prop passing.

<AmiableForm
  process={() => {}}
  processInvalid={() => {}}
  validate={() => {}}
  transform={() => {}}
  initialValues={{}}>
  ...
</AmiableForm>

Prop Name	Type	Description
process	function(values, ...args)	function called when a valid form is submitted	required
processInvalid	function(values, formMeta, fields)	function called when an invalid form is submitted
validate	function(values)	return error string
transform	function({ current, next })	return transformed state
initialValues	plain object	the initial values to set to the form

useField

The useField hook is used to define a field component. amiable-form doesn't provide a Field component and instead provides this hook. This is a design choice to increase compatibility to various form layouts making its integration a more amiable task.

The useField hook will only cause renders when the value for that field changes.

const YourField = () => {
  const { value, onChange } = useField({ name: 'field1' })
  return <input value={value} onChange={onChange} />
}

Input Key Name	Type	Description
name	string	The name of the field and key in the values object. The name can use a path following the same convention as lodash's set and get functions.	required
validators	[function(), ...]	An array of validation function
parse	function()
format	function()
parseWhenFocused	boolean
custom	dunno

The useField hook returns many variables to accommodate a variety of situations.

Return Name	Type	Description
value	any	the current value of the field
submitted	boolean	if the form has attempted to be submitted
setValue	function()	sets the value of the field
setVisited	function()	marks the field as visited
setFocused	function()	marks the field as focused
onChange	function(ev)	helper handler, calls setValue
onBlur	function(ev)	helper handler, calls setVisited()
error	string	contains error messages from the validator functions
valid	boolean	signals if the field is valid or invalid
touched	boolean	signals if the field's value has ever changed
visited	boolean	signals if a user has clicked through a field
dirty	boolean	signals if the value of the field differs from the initial state
cleanValue	any	the initial value of the field(?)

Field Validators

Field level validation is accomplished by providing an array of validation functions to the useField hook under the validators input key. The current field value is passed to each validation function when invoked and the validator will either return undefined for a pass condition or a string containing the error message. The error message from the first failing validator will be set to the error key return value of the useField hook.

Validator Function Exmaples

const required = value => value ? undefined : 'required'

const numeric = value => (!value || /^\\d+$/i.test(value)) ? undefined : 'invalid'

Field Parse and Format

The parse and format functions can be used when the value shown to the user in the form differs from what needs to be saved in the data. For example, date fields might want to display a format of MM/DD/YYYY to the user but store the value as YYYY-MM-DD. The parse function is used to read the information in the field and convert it into the form data format. format is used to convert the form data value into a value to be shown to the user. The parse function can also be used as a way to normalize the user input. By default, the value will be parsed when entered, but can be turned off by setting parseWhenFocused to false.

Validator Function Exmaples

const parse = value => (value && value.toUpperCase()) || undefined

const format = value => (value || '').toLowerCase()

useForm

The useForm hook is the base amiable-forms hook and provides access to the entire state of the form. All of the other hooks are built using useForm. By default, useForm will cause the component it is in to render on every change. To avoid unnecessary renders, the shouldUpdate function needs to be passed into it as an argument.

const never = () => false
const { setValues } = useForm({ shouldUpdate: never })

Input Key Name	Type	Description
shouldUpdate	function({ previous, current })	is given the current and previous form state and returns true if the component should render or false if not

Return Name	Type	Category	Description
setValue	function()	actions
setValues	function()	actions
setField	function()	actions
setMetaValue	function()	actions
removeField	function()	actions
reset	function()	actions
clear	function()	actions
values	object	state
fields	object	state
meta	object	state
cleanValues	object	state
submit	function()	submission
onSubmit	function()	submission
register	function()	registration
deregister	function()	registration

Field Meta

Name	Type	Description
error	string
valid	boolean
touched	boolean
visited	boolean
dirty	boolean
registered	boolean
focused	boolean

Form Meta

Name	Type	Description
touched	boolean
submitted	boolean
visited	boolean
valid	boolean
dirty	boolean
error	string

Helper Utilties

useFieldValue

useArrayField

useRepeated

useFieldCustomMeta

Debug

Solutions to Common Problems

• conditional sections based on form state
• setting form state (or submitting) from external source
• sending additional arguments to the process function
• complex fields
• destructive parse (parseWhenFocused)