This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
================================================
FILE: SECURITY.md
================================================
# Security Policy
## Supported Versions
Use this section to tell people about which versions of your project are
currently being supported with security updates.
| Version | Supported |
| ------- | ------------------ |
| 5.1.x | :white_check_mark: |
| 5.0.x | :x: |
| 4.0.x | :white_check_mark: |
| < 4.0 | :x: |
## Reporting a Vulnerability
Use this section to tell people how to report a vulnerability.
Tell them where to go, how often they can expect to get an update on a
reported vulnerability, what to expect if the vulnerability is accepted or
declined, etc.
================================================
FILE: app/.eslintignore
================================================
build
================================================
FILE: app/.eslintrc.js
================================================
module.exports = {
extends: ["react-app", "welly"],
rules: { "react/react-in-jsx-scope": "off" },
};
================================================
FILE: app/.gitignore
================================================
# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
# dependencies
node_modules
.pnp
.pnp.js
# testing
coverage
# production
build
# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local
.eslintcache
npm-debug.log*
yarn-debug.log*
yarn-error.log*
================================================
FILE: app/.prettierignore
================================================
# testing
coverage
# production
build
# misc
.env.local
.env.development.local
.env.test.local
.env.production.local
npm-debug.log*
yarn-debug.log*
yarn-error.log*
================================================
FILE: app/.stylelintrc.js
================================================
module.exports = {
extends: ["stylelint-config-standard", "stylelint-config-prettier"],
ignoreFiles: ["build/**/*.css"],
};
================================================
FILE: app/README.md
================================================
# App
🧪 A place for trying something interesting.
================================================
FILE: app/package.json
================================================
{
"name": "rcf-app",
"private": true,
"scripts": {
"link-pkg": "yarn link 'react-cool-form'",
"start:auto": "react-scripts start",
"start:dev": "REACT_APP_ENV=dev react-scripts start",
"start:prod": "yarn build && serve -s build",
"build": "react-scripts build",
"lint": "run-s lint:*",
"lint:code": "eslint --fix . --ext .js,.ts,.tsx",
"lint:type": "tsc",
"lint:style": "stylelint --fix \"**/*.{css,ts,tsx}\"",
"lint:format": "prettier -w . -u --loglevel silent",
"clean": "rimraf build",
"eject": "react-scripts eject"
},
"browserslist": {
"production": [
">0.2%",
"not dead",
"not op_mini all"
],
"development": [
"last 1 chrome version",
"last 1 firefox version",
"last 1 safari version"
]
},
"dependencies": {
"@emotion/react": "^11.4.0",
"@types/node": "^16.4.1",
"@types/react": "^17.0.14",
"@types/react-dom": "^17.0.9",
"normalize.css": "^8.0.1",
"react": "^17.0.2",
"react-dom": "^17.0.2",
"react-scripts": "5.0.0",
"typescript": "^4.3.5"
},
"devDependencies": {
"eslint-config-welly": "^1.13.0",
"npm-run-all": "^4.1.5",
"prettier": "^2.3.2",
"rimraf": "^3.0.2",
"serve": "^13.0.2",
"stylelint": "^13.13.1",
"stylelint-config-prettier": "^8.0.2",
"stylelint-config-standard": "^22.0.0"
}
}
================================================
FILE: app/public/index.html
================================================
React Cool Form
================================================
FILE: app/public/manifest.json
================================================
{
"short_name": "REACT COOL IMG",
"name": "REACT COOL IMG",
"icons": [
{
"src": "favicon.ico",
"sizes": "64x64 32x32 24x24 16x16",
"type": "image/x-icon"
},
{
"src": "logo192.png",
"type": "image/png",
"sizes": "192x192"
},
{
"src": "logo512.png",
"type": "image/png",
"sizes": "512x512"
}
],
"start_url": ".",
"display": "standalone",
"theme_color": "#000000",
"background_color": "#ffffff"
}
================================================
FILE: app/public/robots.txt
================================================
# https://www.robotstxt.org/robotstxt.html
User-agent: *
Disallow:
================================================
FILE: app/src/App/index.tsx
================================================
import { Global, css } from "@emotion/react";
import normalize from "normalize.css";
import Playground from "../Playground";
import Automation from "../Automation";
import { root } from "./styles";
export default (): JSX.Element => (
<>
{process.env.REACT_APP_ENV === "dev" ? : }
);
================================================
FILE: app/src/App/styles.ts
================================================
import { css } from "@emotion/react";
// eslint-disable-next-line import/prefer-default-export
export const root = css`
body {
font-family: "Roboto", sans-serif;
}
`;
================================================
FILE: app/src/Automation/index.tsx
================================================
const Automation = (): JSX.Element =>
Automation
;
export default Automation;
================================================
FILE: app/src/Playground/index.tsx
================================================
/* eslint-disable no-console */
import { useForm } from "react-cool-form";
export default () => {
const { form, runValidation } = useForm({
// validate: () => ({ foo: "Required" }),
focusOnError: ["foo"],
});
return (
<>
);
};
================================================
FILE: app/src/index.tsx
================================================
import { StrictMode } from "react";
import ReactDOM from "react-dom";
import App from "./App";
ReactDOM.render(
,
document.getElementById("root")
);
================================================
FILE: app/src/react-app-env.d.ts
================================================
///
///
================================================
FILE: app/src/types/index.d.ts
================================================
declare module "*.css";
================================================
FILE: app/tsconfig.json
================================================
{
"compilerOptions": {
"target": "es5",
"lib": ["dom", "dom.iterable", "esnext"],
"allowJs": true,
"skipLibCheck": true,
"esModuleInterop": true,
"allowSyntheticDefaultImports": true,
"strict": true,
"forceConsistentCasingInFileNames": true,
"noFallthroughCasesInSwitch": true,
"module": "esnext",
"moduleResolution": "node",
"resolveJsonModule": true,
"isolatedModules": true,
"noEmit": true,
"jsx": "react-jsx"
},
"include": ["src"]
}
================================================
FILE: babel.config.json
================================================
{
"presets": [
[
"@babel/env",
{
"loose": true,
"exclude": [
"@babel/plugin-transform-async-to-generator",
"@babel/plugin-transform-regenerator"
]
}
],
"@babel/typescript",
"@babel/react"
]
}
================================================
FILE: bundlesize.config.json
================================================
{
"files": [
{
"path": "dist/index.umd.production.min.js",
"maxSize": "7.2 kB"
}
]
}
================================================
FILE: docs/api-reference/use-controlled.md
================================================
---
id: use-controlled
title: useControlled
---
This hook allows us to integrate with an existing component (usually a [controlled component](https://reactjs.org/docs/forms.html#controlled-components)) or 3rd-party UI library in React Cool Form. With this hook, we can easily to create a reusable controller component to fulfill our needs. See the [useControlled Hook](../getting-started/3rd-party-ui-libraries#2-usecontrolled-hook) to learn more.
:::note
When working with [conditional fields](../examples/conditional-fields), please ensure the hook is wrapped in a component.
:::
```js
const [fieldProps, meta] = useControlled(name, config);
```
## Name
`string`
The name of the field. We must provide it when using this hook.
## Config
An `object` with the following options:
### formId
`string`
The [corresponding ID](./use-form#id) of the `useForm` hook. We only need it when using multiple form hooks at the same time.
### defaultValue
`string`
The default value of the field. Useful for dealing with the case of [conditional fields](../examples/conditional-fields).
### validation
`(value: any, values: FormValues) => any | Promise`
A synchronous/asynchronous function that is used for the [field-level validation](../getting-started/validation-guide#field-level-validation).
### parse
`(...args: any[]) => any`
A function that takes the event object (or parameters) of the target component's `onChange` handler and parses the value of the field that you want to store into the [form state](../getting-started/form-state#about-the-form-state). Useful for data type converting.
### format
`(value: any) => any`
A function that takes the field's value from the [form state](../getting-started/form-state#about-the-form-state) and formats the value to give to the field. Usually used in conjunction with `parse`.
### errorWithTouched
`boolean`
Enable/disable the feature of **filtering untouched errors**, which can help the user focus on typing without being annoyed by the error message. Default is `false`.
```js
// Current state: { errors: { foo: "Required" }, touched: {} }
// Returns "Required"
const [, { error }] = useControlled("foo");
// Current state: { errors: { foo: "Required" }, touched: {} }
// Returns undefined
const [, { error }] = useControlled("foo", { errorWithTouched: true });
// Current state: { errors: { foo: "Required" }, touched: { foo: true } }
// Returns "Required"
const [, { error }] = useControlled("foo", { errorWithTouched: true });
```
### ...restProps
Any other props that will be spread into the `fieldProps`.
## Field Props
An `object` with the following properties:
### name
`string`
The name of the field.
### value
`any`
The value of the field.
### onChange
`(...event: any[]) => void`
An event handler called when the field's value changed.
### onBlur
`(e: React.FocusEvent) => void`
An event handler called when the field loses focus.
### ...restProps
Any other props that were passed to the `config`.
## Meta
An `object` with the following properties:
### error
`string | undefined`
The current validation error of the field.
### isTouched
`boolean`
To indicate whether the field has been touched/visited.
### isDirty
`boolean`
To indicate whether the field has been modified.
## Example
The example demonstrates the basic usage of this hook.
:::note
When using the hook (and not working with [field-array](../getting-started/arrays-and-lists#dealing-with-array-fields)), a default value is required.
:::
```js
import { useControlled } from "react-cool-form";
const Field = ({
as,
name,
defaultValue,
validate,
parse,
format,
errorWithTouched,
...restProps
}) => {
const [fieldProps, { error, isTouched, isDirty }] = useControlled(name, {
defaultValue,
validate,
parse,
format,
errorWithTouched,
...restProps,
});
const Component = as;
return ;
};
```
================================================
FILE: docs/api-reference/use-field-array.md
================================================
---
id: use-field-array
title: useFieldArray
---
This hook supplies you with functions for manipulating the array/list of fields, it's fast! See the [Arrays and Lists](../getting-started/arrays-and-lists) to learn more.
```js
const [fields, helpers] = useFieldArray(name, config);
```
## Name
`string`
The name of the field. We must provide it when using this hook.
## Config
An `object` with the following options:
### formId
`string`
The [corresponding ID](./use-form#id) of the `useForm` hook. We only need it when using multiple form hooks at the same time.
### defaultValue
`string`
The default value of the field. Useful for dealing with the case of [conditional fields](../examples/conditional-fields).
### validation
`(value: any, values: FormValues) => any | Promise`
A synchronous/asynchronous function that is used for the [field-level validation](../getting-started/validation-guide#field-level-validation).
## Fields
`string[]`
An array that holds field names (e.g. `foo[0]`, `foo[1]`), which can be used for the `key` and `name` attributes of a field.
- It refers to the location of the field in the [form state](../getting-started/form-state#about-the-form-state). If the referenced value isn't an `array` type, returns an empty array instead.
- It doesn't include the field data. If you need to access the data, use the [use](./use-form#use) or [getState](./use-form#getstate) methods.
```js
const [fields] = useFieldArray("foo", { defaultValue: [{ name: "Iron Man" }] });
// The first parameter of the callback supplies you a field name (e.g. foo[0], foo[1])
fields.map((fieldName) => (
));
```
## Helpers
An `object` with the following methods:
### push
`(value: FieldValue, options?: Object) => void`
Add a value to the end of an array.
```js
const handleAdd = () => {
push(
{ name: "Iron Man" },
{
shouldTouched: false, // (Default = false) Set the field as touched
shouldDirty: true, // (Default = true) Set the field as dirty
}
);
};
```
### insert
`(index: number, value: FieldValue, options?: Object) => void`
Insert an element at a given index into the array.
```js
const handleInsert = () => {
insert(
0,
{ name: "Iron Man" },
{
shouldTouched: false, // (Default = false) Set the field as touched
shouldDirty: true, // (Default = true) Set the field as dirty
}
);
};
```
### swap
`(indexA: number, indexB: number) => void`
Swap two values in an array.
### move
`(from: number, to: number) => void`
Move an element in an array to another index.
### remove
`(index: number) => FieldValue`
Remove an element at an index of an array and return it.
## Example
The example demonstrates the basic usage of this hook.
```js
import { useForm, useFieldArray } from "react-cool-form";
const App = () => {
const { form } = useForm({
defaultValues: { foo: [{ name: "Iron Man" }] },
});
const [fields, { push, insert, move, swap, remove }] = useFieldArray("foo");
return (
);
};
```
================================================
FILE: docs/api-reference/use-form-methods.md
================================================
---
id: use-form-methods
title: useFormMethods
---
This hook allows us to use [all of the methods](./use-form#methods) provided by React Cool Form from a component at any level. See the [Do It Yourself](../getting-started/3rd-party-ui-libraries#3-do-it-yourself) to learn more.
```js
const methods = useFormMethods(formId);
```
## formId
`string`
The [corresponding ID](./use-form#id) of the `useForm` hook. We only need it when using multiple form hooks at the same time.
## methods
The [methods](./use-form#methods) are the same as the `useForm` hook.
## Example
The example demonstrates the basic usage of this hook.
```js
import { useFormMethods } from "react-cool-form";
const Field = ({ as, name, onFocus, ...restProps }) => {
const { clearErrors, ...otherMethods } = useFormMethods();
const Component = as;
return (
{
clearErrors(name);
if (onFocus) onFocus(e);
}}
{...restProps}
/>
);
};
```
================================================
FILE: docs/api-reference/use-form-state.md
================================================
---
id: use-form-state
title: useFormState
---
This hook can be used for two purposes:
- Isolating re-rendering: It helps us to isolate re-rendering at the component level for performance optimization (see [related article](https://overreacted.io/before-you-memo)). The API design similar to the [use](./use-form#use) method of the `useForm` that maintain a consistent DX for us. See the [Isolating Re-rendering](../getting-started/form-state#isolating-re-rendering) to learn more.
- On state change event: To listen for changes to properties in the [form state](../getting-started/form-state#about-the-form-state) without triggering re-renders. See the [On State Change Event](../getting-started/form-state#on-state-change-event) to learn more.
```js
// Isolating re-rendering mode
const props = useFormState(path, config);
// On state change event mode
useFormState(path, callback, formId);
```
## Path
`string | string[] | Record`
The path of the property we want to access from the [form state](../getting-started/form-state#about-the-form-state). We can construct the return values as follows.
- Every time an accessed value changed that will trigger re-renders. Thus, there're [some guidelines](../getting-started/form-state#best-practices) for us to use the form state.
- You can access the form's values without the `values.` prefix, ya! it's a shortcut for for your convenience.
```js
// Getting a value
const foo = useFormState("values.foo");
// Shortcut for getting a value
const foo = useFormState("foo");
// Array pick
const [foo, bar] = useFormState(["values.foo", "values.bar"]);
// Object pick
const { foo, bar } = useFormState({ foo: "values.foo", bar: "values.bar" });
```
## Config
An `object` with the following options:
### formId
`string`
The [corresponding ID](./use-form#id) of the `useForm` hook. We only need it when using multiple form hooks at the same time.
### defaultValues
`FormValues`
The alternative default values for this hook to return when we didn't provide them via the [defaultValues option](./use-form#defaultvalues) of the `useForm`. Two common use cases of this option are as follows:
- Setting a default value for a field via the `defaultValue` attribute.
- Setting a default value for a field via the `useControlled`'s [defaultValue option](./use-controlled#defaultvalue).
### errorWithTouched
`boolean`
Enable/disable the feature of **filtering untouched errors**, which can help the user focus on typing without being annoyed by the error message. Default is `false`.
```js
// Current state: { errors: { foo: "Required" }, touched: {} }
// Returns { foo: "Required" }
const errors = useFormState("errors");
// Current state: { errors: { foo: "Required" }, touched: {} }
// Returns {}
const errors = useFormState("errors", { errorWithTouched: true );
// Current state: { errors: { foo: "Required" }, touched: { foo: true } }
// Returns { foo: "Required" }
const errors = useFormState("errors", { errorWithTouched: true );
```
## Callback
`(props: any) => void`
It's called on any of the subscribed properties in the [form state](../getting-started/form-state#about-the-form-state) change. It takes the properties as the parameter.
## FormId
`string`
An optional parameter that works the same as the [config.formId](#formid).
## Example
The example demonstrates the basic usage of this hook.
```js
import { useFormState } from "react-cool-form";
// To isolate re-rendering at the component level
const IsolatedComponent = () => {
const foo = useFormState("foo");
return
{foo}
;
};
// To listen for the changes of a field value
useFormState("foo", (foo) => console.log(foo));
```
================================================
FILE: docs/api-reference/use-form.md
================================================
---
id: use-form
title: useForm
---
This is a custom React [hook](https://reactjs.org/docs/hooks-custom.html#using-a-custom-hook) that helps you with building forms. It takes `config` parameters and returns useful methods as follows.
```js
const methods = useForm(config);
```
## Config
An `object` with the following options:
### id
`string`
The ID of the hook, it's used to pair with the related hook(s) of React Cool Form. We only need it when using multiple form hooks at the same time.
### defaultValues
`Record`
Default field values of the form. In most case (especially working with TypeScript), we should use it to initialize a field's value and use the [defaultValue/defaultChecked](https://reactjs.org/docs/uncontrolled-components.html#default-values) attribute for the case of [conditional fields](../examples/conditional-fields). The `defaultValues` also used to compare against the current values to calculate `isDirty` and `dirty`.
- The `defaultValues` is cached **at the first render** within the custom hook. If you want to reset it or [lazily set it](../examples/lazy-default-values), you can use the [reset](#reset) method.
### excludeFields
`string[]`
Tell React Cool Form to exclude field(s) by passing in the `name`/`id`/`class` of the field. You can also exclude a field via the pre-defined `data-rcf-exclude` attribute.
- The `excludeFields` and `data-rcf-exclude` won't affect the functionality of the [useControlled](./use-controlled).
```js {3,12}
const App = () => {
const { form } = useForm({
excludeFields: ["foo", "#bar", ".baz"],
});
return (
);
};
```
👉🏻 See the [Exclude Fields](../getting-started/integration-an-existing-form#exclude-fields) to learn more.
### builtInValidationMode
`"message" | "state" | false`
We can configure the [mode of the built-in validation](../getting-started/validation-guide#displaying-error-messages) as follows:
- `"message"` (default): Returns [a localized message](https://developer.mozilla.org/en-US/docs/Web/API/HTMLObjectElement/validationMessage) that describes the validation constraints that the field does not satisfy (if any)
- `"state"`: Returns the **key of the invalid property** (e.g. "valueMissing", "tooShort", etc.) of the [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) (if any)
- `false`: Disable the [built-in validation](../getting-started/validation-guide#built-in-validation)
### validateOnChange
`boolean`
Tell React Cool Form to run validations on `change` events as well as the [setValue](#setvalue) method. Default is `true`.
### validateOnBlur
`boolean`
Tell React Cool Form to run validations on `blur` events. Default is `true`.
### focusOnError
`boolean | string[] | (names: string[]) => string[]`
Tell React Cool Form to apply focus to the first field with an error upon an attempted form submission. Default is `true`.
- Only native input elements that support [HTMLElement.focus()](https://developer.mozilla.org/en-US/docs/Web/API/HTMLOrForeignElement/focus) will work.
- The focus order is based on the field order (i.e. top-to-bottom and left-to-right).
```js
// Current fields: { foo: "", bar: "", baz: "" }
// Disable this feature
const methods = useForm({ focusOnError: false });
// Change the focus order by passing in field names
const methods = useForm({ focusOnError: ["bar", "foo", "baz"] });
// Change the focus order by modifying existing field names
const methods = useForm({
focusOnError: (names) => {
[names[0], names[1]] = [names[1], names[0]];
return names;
},
});
```
### removeOnUnmounted
`boolean | string[] | (names: string[]) => string[]`
By default, React Cool Form automatically removes the **related state** (i.e. value, error, touched, dirty) and **default value** of an unmounted field for us. However, we can set the `removeOnUnmounted` to `false` to maintain all the data or give it field names to maintain partial data. Default is `true`.
- To keep a default value existing between a dynamically show/hide field, we can set it via `defaultValue` attribute or option.
- If this feature doesn't meet your needs, you can use the [removeField](#removefield) to control what data that you want to remove instead.
```js
// Current values: { foo: "🍎", bar: "🍋", baz: "🥝" }
// Keep all the data
const methods = useForm({ removeOnUnmounted: false });
// Keep partial data (i.e. "bar" and "baz") by passing in field names
const methods = useForm({ removeOnUnmounted: ["foo"] });
// Keep partial data (i.e. "bar" and "baz") by modifying existing field names
const methods = useForm({
removeOnUnmounted: (names) => names.filter((name) => name === "foo"),
});
```
👉🏻 See the [conditional fields](../examples/conditional-fields) example to learn more.
### validate
`(values: FormValues) => FormErrors | false | void | Promise`
A synchronous/asynchronous function that is used for the [form-level validation](../getting-started/validation-guide#form-level-validation). It takes all the form's values and returns any validation errors (or returns `undefined` if there's no error). The validation errors must be in the same shape as the values of the form.
### onSubmit
`(values: FormValues, options: Object, e?: Event) => void | Promise`
The form submission handler will be called when the form is submitted (or when the [submit](#submit) method is called) and validated successfully. It takes the following parameters:
```js
const methods = useForm({
onSubmit: async (
values,
{
getState,
setValue,
setTouched,
setDirty,
setError,
focus,
runValidation,
removeField,
submit,
reset,
},
e
) => {
/* Do something... */
},
});
```
👉🏻 See the [Form Submission](../getting-started/form-submission) to learn more.
### onError
`(errors: FormErrors, options: Object, e?: Event) => void`
The form error handler that is called when the form is submitted (or when the [submit](#submit) method is called) and validated failed. It takes the following parameters:
```js
const methods = useForm({
onError: (
errors,
{
getState,
setValue,
setTouched,
setDirty,
setError,
focus,
runValidation,
removeField,
submit,
reset,
},
e
) => {
/* Do something... */
},
});
```
👉🏻 See the [Form Submission](../getting-started/form-submission) to learn more.
### onReset
`(values: FormValues, options: Object, e?: Event) => void`
The form reset handler that is called when the form is reset (or when the [reset](#reset) method is called). It takes the following parameters:
```js
const methods = useForm({
onReset: (
values,
{
getState,
setValue,
setTouched,
setDirty,
setError,
focus,
runValidation,
removeField,
submit,
reset,
},
e
) => {
/* Do something... */
},
});
```
👉🏻 See the [Reset Form](../getting-started/reset-form) to learn more.
### onStateChange
`(formState: FormState) => void`
The form state change handler that is called on every state change. It's useful for **debugging** or **triggering a handler**.
- Want to trigger a handler based on certain properties in the form state? Check out the [useFormState](./use-form-state) to learn more.
- `formState` is readonly and should not be mutated directly.
```js
const methods = useForm({
onStateChange: (formState) => console.log("State: ", formState),
});
```
## Methods
An `object` with the following methods:
### form
`(element: HTMLElement) => void`
This method allows us to integrate [an existing form](../getting-started/integration-an-existing-form#hook-into-a-form) or [a container where inputs are used](../getting-started/integration-an-existing-form#without-using-a-form-element) with React Cool Form.
### field
`(validateOrOptions: Function | Object) => Function`
This method allows us to do [field-level validation](../getting-started/validation-guide#field-level-validation) and data type conversion via the `ref` attribute. For the data type conversion, React Cool Form supports the [valueAsNumber](https://www.w3.org/TR/2011/WD-html5-20110405/common-input-element-attributes.html#dom-input-valueasnumber), [valueAsDate](https://www.w3.org/TR/2011/WD-html5-20110405/common-input-element-attributes.html#dom-input-valueasdate), and custom parser.
- For your convenience, the values of `` and `` are converted to `number` by default.
- When using this method with the [useControlled](./use-controlled), the functionality of the method will be replaced.
```js
const { field } = useForm();
!value.length && "Required",
valueAsNumber: true, // (Default = false) Returns a number representing the field's value if applicable, otherwise, returns "NaN"
valueAsDate: true, // (Default = false) Returns a Date object representing the field's value if applicable, otherwise, returns "null"
parse: (value) => customParser(value), // Returns whatever value you want through the callback
})}
/>;
```
If you just want to validate the field, there's a shortcut for it:
```js
!value.length && "Required")} />
```
### focus
`(name: string, delay?: number) => void`
This method allows us to apply focus to a field. If you want to focus on the first field of a nested fields, you can just pass in the parent path as below.
:::note
When working with [Arrays and Lists](../getting-started/arrays-and-lists), we need to set `delay` (delay = 0 is acceptable) to wait for a field rendered before applying focus to it.
:::
```js {7,12}
const App = () => {
const { form, focus } = useForm();
useEffect(() => {
// Will focuses on the first field after 0.5 second
// It works the same as `focus("foo.a", 500)`
focus("foo", 500);
}, []);
return (
);
};
```
👉🏻 See the [Applying Focus](../getting-started/arrays-and-lists#applying-focus) to learn more.
### use
`(path: string | string[] | Record, options?: Object) => any`
This method provides us a performant way to use the form state with minimized re-renders. See the [Form State](../getting-started/form-state) to learn more.
### getState
`(path?: string | string[] | Record) => any`
This method allows us to read the form state without triggering re-renders. See the [Reading the State](../getting-started/form-state#reading-the-state) to learn more.
### setValue
`(name: string, value: any | Function, options?: Object) => void`
This method allows us to manually set/clear the value of a field. Useful for creating custom field change handlers.
```js
const { setValue } = useForm();
setValue("fieldName", "value", {
shouldValidate: true, // (Default = "validateOnChange" option) Triggers field validation
shouldTouched: true, // (Default = true) Sets the field as touched
shouldDirty: true, // (Default = true) Sets the field as dirty
});
// We can also pass a callback as the "value" parameter, similar to React's setState callback style
setValue("fieldName", (prevValue) => prevValue.splice(2, 0, "🍎"));
```
We can clear the value of a field by the following way:
```js
setValue("fieldName", undefined); // The field will be unset: { fieldName: "value" } → {}
```
### setTouched
`(name: string, isTouched?: boolean, options?: Object) => void`
This method allows us to manually set/clear the touched of a field. Useful for creating custom field touched handlers.
```js
const { setTouched } = useForm();
// Common use case
setTouched("fieldName");
// Full parameters
setTouched(
"fieldName",
true, // (Default = true) Sets the field as touched
{
shouldValidate: true, // (Default = "validateOnBlur" option) Triggers field validation
}
);
```
We can clear the touched of a field by the following way:
```js
setTouched("fieldName", false); // The touched will be unset: { fieldName: true } → {}
```
### setDirty
`(name: string, isDirty?: boolean) => void`
This method allows us to manually set/clear the dirty of a field. Useful for creating custom field dirty handlers.
```js
const { setDirty } = useForm();
// Common use case
setDirty("fieldName");
```
We can clear the dirty of a field by the following way:
```js
setDirty("fieldName", false); // The dirty will be unset: { fieldName: true } → {}
```
### setError
`(name: string, error: any | Function) => void`
This method allows us to manually set/clear the error of a field. Useful for creating custom field error handlers.
```js
const { setError } = useForm();
setError("fieldName", "Required");
// We can also pass a callback as the "error" parameter, similar to React's setState callback style
setError("fieldName", (prevError) => (prevError ? "Too short" : "Required"));
```
We can clear the error of a field by the following way (or using [clearErrors](#clearerrors)):
```js
setError("fieldName", undefined); // Or any falsy values, the error will be unset: { fieldName: "Required" } → {}
```
### clearErrors
`(name?: string | string[]) => void`
This method allows us to manually clear errors (or an error). Useful for creating custom field error handlers.
```js
const { clearErrors } = useForm();
// Current errors: { foo: { bar: "Required", baz: "Required" }, qux: "Required" }
clearErrors(); // Clears all errors. Result: {}
clearErrors("foo"); // Clears both "foo.bar" and "foo.baz". Result: { qux: "Required" }
clearErrors(["foo.bar", "foo.baz"]); // Clears "foo.bar" and "foo.baz" respectively. Result: { foo: {}, qux: "Required" }
```
### runValidation
`(name?: string | string[], options?: Object) => Promise`
This method allows us to manually run validation for the form or field(s).
- It returns a `boolean` that indicates the validation results, `true` means valid, `false` otherwise.
- Please note, when enabling the [Filter Untouched Field Errors](../getting-started/form-state#filter-untouched-field-errors), only the errors of the touched fields are accessible.
```js
const { runValidation } = useForm();
// Validates the form (i.e. all the fields)
runValidation();
// Validates single field
runValidation("fieldName");
// Validates multiple fields
runValidation(["fieldName1", "fieldName2"]);
// With result
const validateForm = async () => {
const isValid = await runValidation();
console.log("The form is: ", isValid ? "valid" : "invalid");
};
// Full parameters
runValidation("fieldName", {
shouldFocus: true, // (Default = "focusOnError" option) To focus to the first field with an error within the specified fields
});
```
👉🏻 See the [Validation Guide](../getting-started/validation-guide) to learn more.
### removeField
`(name: string, exclude?: string[]) => void`
This method allows us to manually remove the **related state** (i.e. value, error, touched, dirty) and **default value** of a field, it also excludes a field from the form.
- By default, React Cool Form automatically [removes an unmounted field](#removeonunmounted) for us but this method gives us the ability to control what data that we want to remove.
```js {4,10}
const App = () => {
const [show, setShow] = useState(true);
const { form, removeField } = useForm({
removeOnUnmounted: false, // Disable the feature of automatically removing fields
});
const handleToggle = () => {
setShow(!show);
// We can exclude these data: ["defaultValue", "value", "error", "touched", "dirty"]
if (!show) removeField("foo", ["defaultValue"]); // Keep the default value
};
return (
);
};
```
### submit
`(e?: Event) => Promise`
This method allows us to manually submit the form, it returns a promise with the following results. Useful for meeting the needs of custom design.
- Returns a promise with `errors` when any validation errors
- Returns a promise with `values` when the form is validated successfully
```js
const { submit } = useForm({
onSubmit: (values, options, e) => console.log("onSubmit: ", values), // Triggered on form submit + valid
onError: (errors, options, e) => console.log("onError: ", errors), // Triggered on form submit + invalid
});
const handleFormSubmit = async (e) => {
const { errors, values } = await submit(e); // Pass the event object to the event handlers
if (errors) {
// Do something for invalid case
} else {
// Do something for valid case
}
};
```
👉🏻 See the [Form Submission](../getting-started/form-submission) to learn more.
### reset
`(values?: FormValues | Function | null, exclude?: string[] | null, e?: Event) => void`
This method allows us to manually reset the form. It will restore the form to its default values as well as reset/clear all the [related state](../getting-started/form-state#about-the-form-state).
- We can pass `values` as an optional parameter to update the default values.
- We can pass `exclude` as an optional parameter to prevent specific [state](../getting-started/form-state#about-the-form-state) from reset.
```js
const { reset } = useForm({
defaultValues: { firstName: "", lastName: "" },
onReset: (values, options, e) => console.log("onReset: ", values), // Triggered on form reset
});
const handleFormReset = (e) => {
reset(
{ firstName: "Welly", lastName: "Shen" }, // Update the default values
["isSubmitted", "submitCount"], // Don't reset the "isSubmitted" and "submitCount" state
e // Pass the event object to the "onReset" handler
);
// We can also pass a callback as the "values" parameter, similar to React's setState callback style
reset((prevValues) => ({ ...prevValues, firstName: "Bella" }));
};
```
👉🏻 See the [Reset Form](../getting-started/reset-form) to learn more.
================================================
FILE: docs/api-reference/utility-functions.md
================================================
---
id: utility-functions
title: Utility Functions
---
React Cool Form exports useful utility functions that can help you handle [complex structures](../getting-started/complex-structures) efficiently.
```js
import { get, set, unset } from "react-cool-form";
```
## get
`(object: Record, path: string, defaultValue?: unknown) => any`
Gets the value at path of object. If the resolved value is `undefined`, the `defaultValue` is returned in its place.
```js {8}
import { useForm, get } from "react-cool-form";
const { form } = useForm({
defaultValues: { foo: { bar: { baz: "" } } },
validate: (values) => {
const errors = {};
if (!get(values, "foo.bar.baz", "")) errors.foo.bar.baz = "Required";
return errors;
},
// ...
});
```
## set
`(object: Record, path: string, value: unknown, immutable?: boolean) => any`
Sets the value at `path` of `object`. If a portion of `path` doesn't exist, it's created. Arrays are created for missing index properties while objects are created for all other missing properties.
```js {10,12}
import { useForm, set } from "react-cool-form";
const { form } = useForm({
defaultValues: { foo: { bar: { baz: "" } } },
validate: (values) => {
const errors = {};
if (!values.foo.bar.baz) {
// Mutable way
set(errors, "foo.bar.baz", "Required");
// Immutable way
errors = set(errors, "foo.bar.baz", "Required", true);
}
return errors;
},
// ...
});
```
## unset
`(object: Record, path: string, immutable?: boolean) => any`
Removes the property at `path` of `object`.
- If the property remains empty, the parent properties will be removed as well.
- It will clear the redundant `empty` or `undefined` element(s) of an array.
```js {12,14}
import { useForm, unset } from "react-cool-form";
const { form } = useForm({
defaultValues: { foo: { bar: { baz: "" } } },
validate: (values) => {
const errors = {};
if (!values.foo.bar.baz) {
// ...
} else {
// Mutable way
unset(errors, "foo.bar.baz");
// Immutable way
errors = unset(errors, "foo.bar.baz", true);
}
return errors;
},
// ...
});
```
================================================
FILE: docs/examples/arrays-and-lists.md
================================================
---
id: arrays-and-lists
title: Arrays and Lists
hide_table_of_contents: true
---
This example demonstrates how to work with array fields in React Cool Form.
================================================
FILE: docs/examples/basic.md
================================================
---
id: basic
title: Basic
hide_table_of_contents: true
---
This example demonstrates how to use form inputs (input, select, and textarea) to build a form with no validation.
================================================
FILE: docs/examples/built-in-validation.md
================================================
---
id: built-in-validation
title: Built-in Validation
hide_table_of_contents: true
---
This example demonstrates how to use [HTML form validation](https://developer.mozilla.org/en-US/docs/Learn/Forms/Form_validation#Using_built-in_form_validation) to validate a form.
================================================
FILE: docs/examples/checkboxes.md
================================================
---
id: checkboxes
title: Checkboxes
hide_table_of_contents: true
---
This example demonstrates how to use React Cool Form with a checkbox group and how to validate it. Given that fields all the share `name` and the respective `value`, React Cool Form will automatically bind them into a single array.
================================================
FILE: docs/examples/complex-strcutures.md
================================================
---
id: complex-structures
title: Complex Structures
hide_table_of_contents: true
---
This example demonstrates how to handle [Complex Structures](../getting-started/complex-structures) in React Cool Form.
================================================
FILE: docs/examples/conditional-fields.md
================================================
---
id: conditional-fields
title: Conditional Fields
hide_table_of_contents: true
---
By default, when a form input element ([input](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input), [select](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select), and [textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)) is unmounted, React Cool Form will auto remove it for us. Useful for dealing with conditional fields, let's take a look at the following example:
================================================
FILE: docs/examples/custom-field.md
================================================
---
id: custom-field
title: Custom Field
hide_table_of_contents: true
---
This example demonstrates how to combine the [useFormState](../api-reference/use-form-state) and [useFormMethods](../api-reference/use-form-methods) to DIY a custom field.
================================================
FILE: docs/examples/field-level-validation.md
================================================
---
id: field-level-validation
title: Field-level Validation
hide_table_of_contents: true
---
This example demonstrates how to validate a form by the [field](../api-reference/use-form#field) method of React Cool Form.
================================================
FILE: docs/examples/form-level-validation.md
================================================
---
id: form-level-validation
title: Form-level Validation
hide_table_of_contents: true
---
This example demonstrates how to validate a form by the [validate](../api-reference/use-form#validate) option of React Cool Form.
================================================
FILE: docs/examples/form-submission.md
================================================
---
id: form-submission
title: Form Submission
hide_table_of_contents: true
---
This example demonstrates how to submit a form in React Cool Form.
================================================
FILE: docs/examples/isolating-rerendering.md
================================================
---
id: isolating-rerendering
title: Isolating Re-rendering
hide_table_of_contents: true
---
This example demonstrates how to isolate re-rendering at the component level via the [useFormState](../api-reference/use-form-state) hook.
================================================
FILE: docs/examples/lazy-default-values.md
================================================
---
id: lazy-default-values
title: Lazy Default Values
hide_table_of_contents: true
---
This example demonstrates how to set [defaultValues](../api-reference/use-form#defaultvalues) lazily.
================================================
FILE: docs/examples/material-ui.md
================================================
---
id: material-ui
title: Material-UI
hide_table_of_contents: true
---
This example demonstrates the easiest way to integrate [Material-UI](https://material-ui.com) with your form that you have never seen 😎.
================================================
FILE: docs/examples/multi-select.md
================================================
---
id: multi-select
title: Multi-select
hide_table_of_contents: true
---
This example demonstrates how to use React Cool Form with a multi-select input. Given the select element a `multiple` attribute. React Cool Form will automatically bind the options into a single array.
================================================
FILE: docs/examples/radio-group.md
================================================
---
id: radio-group
title: Radio Group
hide_table_of_contents: true
---
This example demonstrates how to use React Cool Form with a radio group.
================================================
FILE: docs/examples/react-select.md
================================================
---
id: react-select
title: React Select
hide_table_of_contents: true
---
This example demonstrates how to use React Cool Form's [useControlled](../api-reference/use-controlled) hook to integrate [React Select](https://react-select.com) with your form.
================================================
FILE: docs/examples/reset-form.md
================================================
---
id: reset-form
title: Reset Form
hide_table_of_contents: true
---
This example demonstrates how to reset a form in React Cool Form.
================================================
FILE: docs/examples/validation-with-schema.md
================================================
---
id: validation-with-schema
title: Validation with Schema
hide_table_of_contents: true
---
This example demonstrates how to validate a form with a 3rd-party (e.g. [Yup](https://github.com/jquense/yup) or [Joi](https://github.com/sideway/joi)).
================================================
FILE: docs/examples/virtualized-lists.md
================================================
---
id: virtualized-lists
title: Virtualized Lists
hide_table_of_contents: true
---
When working with millions of list items, I'd like to recommend using [React Cool Virtual](https://github.com/wellyshen/react-cool-virtual) to virtualized the list for better performance. It works nicely with React Cool Form, let's dive into it.
================================================
FILE: docs/examples/without-form-element.md
================================================
---
id: without-form-element
title: Without
);
};
```
## 2. [useControlled Hook](../api-reference/use-controlled)
[Controlled components](https://reactjs.org/docs/forms.html#controlled-components) with highly customized and full features like [React Select](https://react-select.com) or [React Datepicker](https://reactdatepicker.com). We can use React Cool Form's [useControlled](../api-reference/use-controlled) hook to create a reusable controller component for them in a flexible and performant way.
:::note
When using the hook (and not working with [field-array](./arrays-and-lists#dealing-with-array-fields)), a default value is required.
:::
[](https://codesandbox.io/s/rcf-react-select-djsl1?fontsize=14&hidenavigation=1&theme=dark)
```js
import { useForm, useControlled } from "react-cool-form";
import Select from "react-select";
const Field = ({ as, name, ...restProps }) => {
const [fieldProps] = useControlled(name, restProps);
const Component = as;
return ;
};
const options = [
{ label: "React", value: "react" },
{ label: "Vue", value: "vue" },
{ label: "Angular", value: "angular" },
{ label: "Svelte", value: "svelte" },
];
const App = () => {
const { form } = useForm({
defaultValues: { framework: "" }, // We must provide a default value for the controlled field
excludeFields: ["#framework"], // Exclude the internal input element of React-Select by ID
onSubmit: (values) => console.log("onSubmit: ", values),
});
return (
);
};
```
## 3. Do It Yourself
If the above solutions can't meet your needs then you can set up a custom field with the [API](../api-reference/use-form#methods) of React Cool Form. The following example demonstrates how to combine the [useFormState](../api-reference/use-form-state) and [useFormMethods](../api-reference/use-form-methods) to DIY a custom field with full validation UX.
[](https://codesandbox.io/s/rcf-custom-field-p9lqi?fontsize=14&hidenavigation=1&theme=dark)
```js
import { useForm, useFormState, useFormMethods } from "react-cool-form";
import { TextField, Button } from "@material-ui/core";
const Field = ({ as, name, onChange, onBlur, ...restProps }) => {
const value = useFormState(`values.${name}`);
const { setValue, setTouched } = useFormMethods();
const Component = as;
return (
{
setValue(name, e.target.value); // Update the field's value and set it as touched
if (onChange) onChange(e);
}}
onBlur={(e) => {
setTouched(name); // Set the field as touched for displaying error (if it's not touched)
if (onBlur) onBlur(e);
}}
{...restProps}
/>
);
};
const App = () => {
const { form, use } = useForm({
defaultValues: { username: "" },
// excludeFields: ["username"], // You can also exclude the field here
validate: ({ username }) => {
const errors = {};
if (!username.length) errors.username = "Required";
return errors;
},
onSubmit: (values) => console.log("onSubmit: ", values),
});
const errors = use("errors");
return (
);
};
```
================================================
FILE: docs/getting-started/accessibility.md
================================================
---
id: accessibility
title: Accessibility (a11y)
hide_table_of_contents: true
---
Web accessibility (a.k.a [a11y](https://en.wiktionary.org/wiki/a11y)) is the design and creation of websites that can be used by everyone. Accessibility support is necessary to allow assistive technology to interpret web pages. React Cool Form is designed to keep your input elements **clean** that helps you build accessible forms by using standard HTML techniques.
- Provide [`
