@bscop/use-form
v2.1.0
Published
A custom React hook handle form.
Downloads
8
Readme
@bscop/use-form
A custom React hook handle form.
Install
npm i @bscop/use-form
Usage
import useForm from "@bscop/use-form";
function App () {
const { onSubmit, pending, register } = useForm(
{
email: {
label: "Email",
schema: [
{
id: "required",
},
],
}
}
);
const send =
(payload) => {
fetch("/", { method: "POST", body: JSON.stringify(payload) })
.then(
() => {
// ...
}
)
};
return (
<form onSubmit={onSubmit(send)}>
<div>
<label>
Email:
<input {...register("email", { type: "email" })}/>
</label>
</div>
<button disabled={pending} type="submit">Save</button>
</form>
);
}
API
const {
debug,
errors,
forceValue,
pending,
onSubmit,
register,
resetForm,
unregister,
valueOf,
} : HookResult = useForm(config: FormConfig);
FormConfig
When executing useForm
we pass to an object to configure the form.FormConfig
is an object whose keys correspond to name of inputs present in the form, and values contains the configuration for each field (Field
).
const fieldEmailConfig : Field = {
schema: [
{
id: "required",
},
]
};
const fieldPasswordConfig : Field = {
};
const formConfig : FormConfig = {
email: fieldEmailConfig,
password: fieldPasswordConfig,
}
useForm(formConfig);
Each field may have following configuration properties:
defaultValue
([string]
) : it's used as initial value, and after the form is reset, or the field in unregistered.label
(string
) : it's used to reference the field in validation error message.schema
([Rule[]]
) : it specifies the rules the field value must respect - more on this subject later.value
([string|string[]]
) : it specifies the initial value of the field - it can be a list of values to accomodate for the possibility of checkbox, and select to have multiple value selected at the same time.
Validation schema
It's a list of validation the field value must pass in order to be considered valid. Each validation validation rule must have an id
field that matches the name of a built-in rule.
Built-in rules are:
- required :
{ id: "required" }
. - max length :
{ id: "maxlen", attrs: { size: number } }
. - min length :
{ id: "minlen", attrs: { size: number } }
. - format :
{ id: "format", attrs: { regexp : string} }
. - range :
{ id: "range", attrs: { range : number[] } }
. - date :
{ id: "date" }
. - one of :
{ id: "oneof", attrs: { options : string[] } }
.
Each rule can optionally also specify a message to override the default message; eg.
useForm(
{
name: {
schema: [
{
id: "required",
message: "Did you forget something?",
},
]
}
}
)
It's also possible to specify a custom validation rule inline; eg.
useForm(
{
name: {
schema: [
{
validate (
name : string,
label : string,
value : string|string[],
rule : Rule,
formState : unknown
) : undefined|string {
/**
* Returns undefined when field value is valid;
* otherwise return a string describing the error.
* This string is meant to be rendered as validation error
* below the field.
*/
const isValid = computeIsValid(value);
if (isValid) {
return undefined;
}
return "The value is not valid.";
}
}
]
}
}
)
HookResult
useForm
returns an object with the following properties:
debug
(() => void
) : print the state of the form.errors
(null | Record<keyof FormConfig, string>
) : contains validation error for each field in the form; it'snull
if the form is valid (or validation didn't run yet).forceValue
((name : string, value : string|string[]) => void, shouldValidate ?: boolean
) : programatically set the value of a field, and trigger validation.valueOf
((name : string) => string|string[]
) : return the value of a given field; for checkbox, and select[multiple] it returns a list of values.pending
(boolean
) : it is true if the submit is in progress - it is recommended to use it to mark the submit button as disabled.onSubmit
((handler : Record<keyof FormConfig, string>) => (event : React.FormEvent) => void
) : handles the submit of the form - the actual request is executed by thehandler
defined in user-land.register
((name : string, attrs ?: Record<string, string>) => FieldAttributes
) : returns the attributes needed to control the field.
import useForm from "@bscop/use-form";
function App () {
const { onSubmit, pending, register } = useForm(
// ...
);
const send = (payload) => {};
return (
<form onSubmit={onSubmit(send)}>
<div>
<label>
Email:
<input {...register("email", { type: "email" })}/>
</label>
</div>
<button disabled={pending} type="submit">Save</button>
</form>
);
}
resetForm
(() => void
) : reset the value of all the fields.unregister
((name : string) => void
) : reset the state of one (or many) form field that becomes unnecessary.
Contribute
Read the guidelines.
Run tests
npm test
Coverage
Coverage reports are hosted on codecov.
npm run badge:coverage -- --token=<guid>
Bruno Scopelliti
www.brunoscopelliti.com