Skip to main content

useControlled

This hook allows us to integrate with an existing component (usually a controlled component) 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 to learn more.

note

When working with conditional fields, please ensure the hook is wrapped in a component.

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 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.

validation#

(value: any, values: FormValues) => any | Promise<any>

A synchronous/asynchronous function that is used for the 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. Useful for data type converting.

format#

(value: any) => any

A function that takes the field's value from 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.

// 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), a default value is required.

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 <Component {...fieldProps} />;
};