react-use-form-state
v0.13.2TypeScript
React hook for managing form and inputs state
0/weekUpdated 3 years agoMITUnpacked: 92.0 KB
Published by Waseem Dahman
npm install react-use-form-state
react-use-form-state
- Motivation📖 Table of Contents
- Getting Started
- Examples
- Basic Usage
- Initial State
- Global Handlers
- Advanced Input Options
- Custom Input Validation
- Check If the Form State Is Pristine
- Without Using a Element
- Labels
- Custom Controls
- Updating Fields Manually
- Resetting The Form State
- Working with TypeScript
- API
- initialState
- formOptions
- formOptions.onBlur
- formOptions.onChange
- formOptions.onTouched
- formOptions.onClear
- formOptions.onReset
- formOptions.validateOnBlur
- formOptions.withIds
- [[formState, inputs]](#formstate-inputs)
- Form State
- Input Types
- Input Options
- License
Motivation
Managing form state in React can be a bit unwieldy sometimes. There are plenty of great solutions already available that make managing forms state a breeze. However, many of those solutions are opinionated, packed with tons of features that may end up not being used, and/or require shipping a few extra bytes!
Luckily, the recent introduction of React Hooks and the ability to write custom hooks have enabled new possibilities when it comes sharing state logic. Form state is no exception!
react-use-form-state is a small React Hook that attempts to simplify managing form state, using the native form input elements you are familiar with!
Getting Started
To get it started, add react-use-form-state to your project:
``
npm install --save react-use-form-state
Please note that react-use-form-state requires react@^16.8.0 as a peer dependency.
Examples
$3
`jsx
import { useFormState } from 'react-use-form-state';
export default function SignUpForm({ onSubmit }) {
const [formState, { text, email, password, radio }] = useFormState();
function handleSubmit(e) {
// ...
}
return (
);
}
`
From the example above, as the user fills in the form, the
object will look something like this:`js
{
values: {
name: 'Mary Poppins',
email: 'mary@example.com',
password: '1234',
plan: 'free',
},
touched: {
name: true,
email: true,
password: true,
plan: true,
},
validity: {
name: true,
email: true,
password: false,
plan: true,
},
errors: {
password: 'Please lengthen this text to 8 characters or more',
},
clear: Function,
clearField: Function,
reset: Function,
resetField: Function,
setField: Function,
}
`$3
takes an initial state object with keys matching the names of the inputs.`jsx
export default function RentCarForm() {
const [formState, { checkbox, radio, select }] = useFormState({
trip: 'roundtrip',
type: ['sedan', 'suv', 'van'],
});
return (
);
}
`$3
supports a variety of form-level event handlers that you could use to perform certain actions:`jsx
export default function RentCarForm() {
const [formState, { email, password }] = useFormState(null, {
onChange(e, stateValues, nextStateValues) {
const { name, value } = e.target;
console.log(the ${name} input has changed!);
},
});
return (
<>
);
}
`$3
provides a quick and simple API to get started with building a form and managing its state. It also supports HTML5 form validation out of the box.`jsx
`While this covers that majority of validation cases, there are times when you need to attach custom event handlers or perform custom validation.
For this, all input functions provide an alternate API that allows you attach input-level event handlers such as
and onBlur, as well as providing custom validation logic.`jsx
export default function SignUpForm() {
const [state, { text, password }] = useFormState();
return (
<>
name: 'password',
onChange: e => console.log('password input changed!'),
onBlur: e => console.log('password input lost focus!'),
validate: (value, values, e) => validatePassword(value),
validateOnBlur: true,
})}
/>
);
}
`$3
The example above demonstrates how you can determine the validity of an input by passing a
method. You can also specify custom validation errors using the same method.The input is considered valid if this method returns
true or undefined.Any truthy value other than
true returned from this method will make the input invalid. This returned value is used as a custom validation error that can be retrieved from state.errors.For convenience, empty collection values such as empty objects, empty arrays, empty maps, empty sets are not considered invalidation errors, and if returned the input will be valid.
`jsx
name: 'password', // can also return objects, arrays, etc, for more complex error objects
validate: (value, values, event) => {
if (!value.trim()) {
return 'Password is required';
}
if (!STRONG_PASSWORD_REGEX.test(value)) {
return 'Password is not strong enough';
}
},
})}
/>
`If the input's value is invalid based on the rules specified above, the form state will look similar to this:
js
{
validity: {
password: false,
},
errors: {
password: 'Password is not strong enough',
}
}
`If the
method is not specified, useFormState will fallback to the HTML5 constraints validation to determine the validity of the input along with the appropriate error message.$3
useFormState exposes a pristine object, and an isPristine() helper via formState that you can use to check if the user has made any changes.This can be used for a Submit button, to disable it, if there are no actual changes to the form state:
`js
function PristineForm() {
const [formState, { text, password }] = useFormState();
return (
);
}
`Checking if a field is pristine is done with simple equality
, with some exceptions. This can be overridden per field by providing a custom compare function.Note that a
compare function is required for raw inputs, otherwise, if not specified, the pristine value of a raw input will always be set to false after a change.`jsx
name: 'userObj',
compare(initialValue, value) {
// returns a boolean indicating if the changed value is equal to the initial value
return isEqualDeep(initialValue, value);
},
})}
/>
`$3
is not limited to actual forms. It can be used anywhere inputs are used.`jsx
function LoginForm({ onSubmit }) {
const [formState, { email, password }] = useFormState();
return (
);
}
`$3
As a convenience,
provides an optional API that helps with pairing a label to a specific input.formOptions.withIds is enabled, a label can be paired to an input by using input.label(). This will populate the label's htmlFor attribute for an input with the same parameters.`js
const [formState, { label, text, radio }] = useFormState(initialState, {
withIds: true, // enable automatic creation of id and htmlFor props
});return (
);
`Note that this will override any existing
prop if specified before calling the input functions. If you want the id to take precedence, it must be passed _after_ calling the input types like this:`jsx
`$3
provides a raw type for working with controls that do not use React's SyntheticEvent system. For example, controls like react-select or react-datepicker have onChange and value props that expect a custom value instead of an event.To use this, your custom component should support an
onChange() event which takes the value as a parameter, and a value prop which is expected to contain the value. Note that if no initial value is given, the component will receive a value prop of an empty string, which might not be what you want. Therefore, you must provide an initial value for raw() inputs when working with custom controls.`js
import DatePicker from 'react-datepicker';function Widget() {
const [formState, { raw }] = useFormState({ date: new Date() });
return (
<>
);
}
`You can also provide an
option with a return value in order to map the value passed from the custom control's onChange to a different value in the form state.`js
function Widget() {
const [formState, { raw }] = useFormState({ date: new Date() });
return (
<>
name: 'date',
onChange: date => date.toString();
})}
value={new Date(formState.date)}
/>
);
}
`Note that
for a raw value _must_ return a value.Many raw components do not support
onBlur() correctly. For these components, you can use touchOnChange to mark a field as touched when it changes instead of on blur:`js
function Widget() {
const [formState, { raw }] = useFormState({ date: new Date() });
return (
<>
name: 'date',
touchOnChange: true,
})}
/>
);
}
`$3
There are cases where you may want to update the value of an input manually without user interaction. To do so, the
method can be used.`js
function Form() {
const [formState, { text }] = useFormState(); function setNameField() {
// manually setting the value of the "name" input
formState.setField('name', 'Mary Poppins');
}
return (
<>
);
}
`Please note that when
is called, any existing errors that might have been set due to previous interactions from the user will be cleared, and both of the validity and the touched states of the input will be set to true.It's also possible to clear a single input's value or to reset it to its initial value, if provided, using
formState.clearField and formState.resetField respectively.As a convenience you can also set the error value for a single input using
formState.setFieldError.$3
The form state can be cleared or reset back to its initial state if provided at any time using
formState.clear and formState.reset respectively.`js
function Form() {
const [formState, { text, email }] = useFormState({
email: 'hello@example.com',
});
return (
<>
);
}
`Working with TypeScript
When working with TypeScript, the compiler needs to know what values and inputs
is expected to be working with.For this reason,
useFormState accepts an optional type argument that defines the state of the form and its fields which you could use to enforce type safety.`ts
interface LoginFormFields {
username: string;
password: string;
remember_me: boolean;
}const [formState, { text }] = useFormState();
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
// OK
formState.values.username
// Error
formState.values.doesNotExist
`By default,
will use the type any for the form state and its inputs if no type argument is provided. Therefore, it is recommended that you provide one.By default, the
errors property will contain strings. If you return complex error objects from custom validation, you can provide an error type:`ts
interface I18nError {
en: string;
fr: string;
}interface LoginFormErrors {
username?: string | I18nError;
password?: string;
}
const [formState, { text }] = useFormState();
formState.errors.username; // Will be undefined, a string, or an I18nError.
`API
js
import { useFormState } from 'react-use-form-state';function FormComponent()
const [formState, inputs] = useFormState(initialState, formOptions);
return (
// ...
)
}
`$3
takes an optional initial state object with keys as the name property of the form inputs, and values as the initial values of those inputs (similar to defaultValue/defaultChecked).$3
useFormState also accepts an optional form options object as a second argument with following properties:####
formOptions.onBlurA function that gets called upon any
of the form's inputs. This functions provides access to the input's blur SyntheticEventjs
const [formState, inputs] = useFormState(null, {
onBlur(e) {
// accessing the inputs target that triggered the blur event
const { name, value, ...target } = e.target;
},
});
`####
A function that gets triggered upon any
of the form's inputs, and before updating formState.This function gives you access to the input's
change SyntheticEvent, the current formState, the next state after the change is applied.`js
const [formState, inputs] = useFormState(null, {
onChange(e, stateValues, nextStateValues) {
// accessing the actual inputs target that triggered the change event
const { name, value, ...target } = e.target;
// the state values prior to applying the change
formState.values === stateValues; // true
// the state values after applying the change
nextStateValues;
// the state value of the input. See Input Types below for more information.
nextStateValues[name];
},
});
`####
A function that gets called after an input inside the form has lost focus, and is marked as touched. It will be called once throughout the component life cycle. This functions provides access to the input's
SyntheticEvent.`js
const [formState, inputs] = useFormState(null, {
onTouched(e) {
// accessing the inputs target that triggered the blur event
const { name, value, ...target } = e.target;
},
});
`####
A function that gets called after calling
indicating that all fields in the form state are cleared successfully.`js
const [formState, inputs] = useFormState(null, {
onClear() {
// form state was cleared successfully
},
});formState.clear(); // clearing the form state
`####
A function that gets called after calling
indicating that all fields in the form state are set to their initial values.`js
const [formState, inputs] = useFormState(null, {
onReset() {
// form state was reset successfully
},
});
formState.reset(); // resetting the form state
`####
By default, input validation is performed on both of the
and the blur events. Setting validateOnBlur to true will limit input validation to be only performed on blur (when the input loses focus). When set to false, input validation will only be performed on change.####
formOptions.withIdsIndicates whether
should generate and pass an id attribute to its fields. This is helpful when working with labels.It can be one of the following:
A
boolean indicating whether input types should pass an id attribute to the inputs (set to false by default).`js
const [formState, inputs] = useFormState(null, {
withIds: true,
});
`Or a custom id formatter: a function that gets called with the input's name and own value, and expected to return a unique string (using these parameters) that will be as the input id.
js
const [formState, inputs] = useFormState(null, {
withIds: (name, ownValue) =>
ownValue ? MyForm-${name}-${ownValue} : MyForm-${name},
});
`Note that when
is set to false, applying input.label() will be a no-op.$3
The return value of
useFormState. An array of two items, the first is the form state, and the second an input types object.#### Form State
The first item returned by
useFormState.`js
const [formState, inputs] = useFormState();
`An object containing the form state that updates during subsequent re-renders. It also include methods to update the form state manually.
ts
formState = {
// an object holding the values of all input being rendered
values: {
[name: string]: string | string[] | boolean,
}, // an object indicating whether the value of each input is valid
validity: {
[name: string]?: boolean,
},
// an object holding all errors resulting from input validations
errors: {
[name: string]?: any,
},
// an object indicating whether the input was touched (focused) by the user
touched: {
[name: string]?: boolean,
},
// an object indicating whether the value of each input is pristine
pristine: {
[name: string]: boolean,
},
// whether the form is pristine or not
isPristine(): boolean,
// clears all fields in the form
clear(): void,
// clears the state of an input
clearField(name: string): void,
// resets all fields the form back to their initial state if provided
reset(): void,
// resets the state of an input back to its initial state if provided
resetField(name: string): void,
// updates the value of an input
setField(name: string, value: string): void,
// sets the error of an input
setFieldError(name: string, error: string): void,
}
`#### Input Types
The second item returned by
.`js
const [formState, input] = useFormState();
`An object with keys as input types. Each type is a function that returns the appropriate props that can be spread on the corresponding input.
The following types are currently supported:
| Type and Usage | State Shape |
| --------------------------------------------------------------- | -------------------------------------------------------------------------- |
|
| { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: Array |
| | { [name: string]: boolean } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: string } |
| | { [name: string]: Array |
| | { [name: string]: string } |
| | N/A – input.label() is stateless and thus does not affect the form state |
| | { [name: string]: any } |#### Input Options
Alternatively, input type functions can be called with an object as the first argument. This object is used to extend the functionality of the input. This includes attaching event handlers and performing input-level custom validation.
`jsx
name: 'username',
validate: value => validateUsername(value),
validateOnBlur: true,
})}
/>
`The following options can be passed:
| key | Description |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
| Required. The name of the input. |
| value: string | The input's own value. Only required by the radio input, and optional for the checkbox input. |
| onChange(e): void | Optional. A change event handler that's called with the input's change SyntheticEvent. |
| onBlur(e): void | Optional. A blur event handler that's called with the input's blur SyntheticEvent. |
| validate(value, values, e): any | Optional (required for raw inputs). An input validation function that determines whether the input value is valid. It's called with the input value, all input values in the form, and the change/blur event (or the raw value of the control in the case of .raw()). The input is considered valid if this method returns true or undefined. Any truthy value other than true returned from this method will make the input invalid. Such values are used a custom validation errors that can be retrieved from state.errors. HTML5 validation rules are ignored when this function is specified. |
| compare(initialValue, value): any | Optional (required for raw inputs). A comparison function that determines whether the input value is pristine. It's called with the input's initial value, and the input's current value. It must return a boolean indicating whether the form is pristine. |
| validateOnBlur: boolean | Optional. Unspecified by default. When unspecified, input validation is performed on both of the change and the blur events. Setting validateOnBlur to true will limit input validation to be only performed on blur (when the input loses focus). When set to false, input validation will only be performed on change. |
| touchOnChange: boolean | Optional. false by default. When false, the input will be marked as touched when the onBlur() event handler is called. For custom controls that do not support onBlur, setting this to true will make it so inputs will be marked as touched when onChange()` is called instead. |License
MIT