👋
Welcome to react-form-state-hooks
Manage your React form state with hooks and helpful components.
🏠 Homepage
Install
npm install react-form-state-hooks
Browser Compatibility
This library uses modern JavaScript methods, so polyfills will be needed for developers supporting legacy browsers.
Performance & Control Considerations
There are two implementations - one for uncontrolled forms and one for controlled. Controlled forms solve some problems but come with some performance challenges when the data is managed by a single store. To avoid this, it's recommended to add basic memoization to all inputs being controlled, as well as any nested form sections. Uncontrolled forms do not suffer from the same performance challenges, but make it harder to take control of an input's value programmatically, which requires a ref or additional complexity.
🚀 Usage
useFormState
import { useFormState } from 'react-form-state-hooks/uncontrolled';
import { useFormState } from 'react-form-state-hooks/controlled';
useFormState
is the primary hook for managing a form's state. Alone it's a simple tool for managing form state, but it
can be nested and combined with the other hooks and utilities to provide state management for complex form structures.
Used with a React Context it provides robust logic with a minimum of boilerplate.
There is a simple example of this in the uncontrolled and controlled examples.
useListFormState
import { useListFormState } from 'react-form-state-hooks/uncontrolled';
import { useListFormState } from 'react-form-state-hooks/controlled';
useListFormState
takes an array of data and exposes it with a similar interface as useFormState
.
It supports simple add/remove and with proper memoization can prevent unnecessary renders for large
lists.
There is a simple example of this in the uncontrolled and controlled examples.
Context Utilities
import { FormStateContext, connectFormStateInput } from 'react-form-state-hooks/uncontrolled';
import { FormStateContext, connectFormStateInput } from 'react-form-state-hooks/controlled';
FormStateContext
is a React Context for providing the current FormState
or ListFormState
to a set of components.
<FormStateContext.Provider value={useFormState()}>
...
</FormStateContext.Provider>
Apart from assisting with the prop-drilling issue, this context also allows you to reduce the boilerplate for writing
your form, using the provided connectFormStateInput
higher-order component.
const ConnectedInput = connectFormStateInput('input');
<FormStateContext.Provider value={useFormState()}>
<label htmlFor="foo">Foo</label>
<ConnectedInput id="foo" name="foo" />
</FormStateContext.Provider>
connectFormStateInput
is a higher order component that links the provided component to FormStateContext
, providing a
standard input onChange
event handler hooked into the context. The uncontrolled implementation will derive
defaultValue
from the context, while controlled syncs value
.
You can see these utilities in action in the uncontrolled and controlled examples.
You can also provide your own context to connectFormStateInput
if for whatever reason you have an existing context to use.
Run tests
npm test
Author
- Github: @bvalyou
🤝 Contributing
Contributions, issues, and feature requests are welcome!
Show your support
Give a
📝 License
Copyright © 2020 Benjamin Valyou.
This project is MIT licensed.
This README was initially generated with
The API Reference was generated by jsdoc-to-markdown