index.d.md

Table of contents

• index.d.ts
  • Functions
    • useForm
    • getForms
    • FormProvider
  • Interfaces
    • ChangeHandler
    • UseForm
    • FormProviderProps
    • FieldValueAndError
    • GeneratedProps
    • ValidateParams
  • Types
    • SubmitCallback
    • FieldValues
    • FieldValuesAndErrors
    • InputTypes
    • GenericObject
    • GeneratePropsFunc
    • InputPropGenerator
    • InputPropGenerators
    • SubmitError
    • ValidationErrors
    • SubmitNotificationType
    • NotificationType
    • Reason
    • NotifyCallback
    • Errors
    • Validators
  • Variables
    • default

index.d.ts

Functions

useForm

Set up a form, or hook into one deifned in FormProvider.

function useForm<N extends string, F extends FieldValues, V extends Validators<F>, S extends SubmitCallback<N, F>>(useFormParams: { name: N; initialState?: F | undefined; validators?: V | undefined; onSubmit?: S | undefined; onNotify?: NotifyCallback<F, NotificationType> | undefined<F>; }): UseForm<N, F, V, keyof ReturnType<V>, S>;

Type parameters

Name	Constraint
N	string
F	FieldValues
V	Validators
S	SubmitCallback<N, F>

Parameters

Name	Type
useFormParams	{ name: N; initialState?: F | undefined; validators?: V | undefined; onSubmit?: S | undefined; onNotify?: NotifyCallback<F, NotificationType> | undefined; }

Return type

UseForm<N, F, V, keyof ReturnType, S>

---

getForms

Returns an unmutable object that contains all the forms in the FormContext.

function getForms(): Forms<Object>;

Return type

Forms

---

FormProvider

Should be declared as high as possible (preferebly in App) in the component tree to survive unmounts of the form components. This way, the form data is saved, even if the user navigates away from any of the form, as long as the component holding this provider is not unmounted.

function FormProvider<T extends Forms<Object>, N1 extends NotificationHandler<NotificationType>, N2 extends NotificationHandler<SubmitNotificationType>>(props: FormProviderProps<T, N1, N2>): Element;

Type parameters

Name	Constraint
T	Forms
N1	NotificationHandler<NotificationType>
N2	NotificationHandler<SubmitNotificationType>

Parameters

Name	Type
props	FormProviderProps<T, N1, N2>

Return type

Element

Interfaces

ChangeHandler

interface ChangeHandler<F, V> {
    (fields: Partial<F>, validations?: V[] | undefined<V>): void;
    (event: FormEvent<Element>, validations: Array<V>): void;
}

Type parameters

Name
F
V

Call

(fields: Partial<F>, validations?: V[] | undefined<V>): void;

Parameters

Name	Type	Description
fields	Partial	An object. The property names must correspond
to one of the fields in initialState.
validations	V[] | undefined	When field values change, they are validated
automatically. By default, only validations with
corresponding names are run, but you can override
which validations to run here.

Return type

void

(event: FormEvent<Element>, validations: Array<V>): void;

Parameters

Name	Type	Description
event	FormEvent	event.target.{name, value, type, checked} are used
to infer the intended change.
validations	Array	When field values change, they are validated
automatically. By default, only validations with
corresponding names are run, but you can override
which validations to run here.

Return type

void

---

UseForm

interface UseForm<N, F, V, KV, OnSubmitCallback extends (args: any[]) => any> {
    name: N;
    fields: FieldValuesAndErrors<F>;
    hasErrors: boolean;
    handleChange: ChangeHandler<F, KV>;
    handleSubmit: (event?: FormEvent<Element> | undefined) => ReturnType<OnSubmitCallback>;
    loading: boolean;
    inputs: InputPropGenerators<F>;
    validators: V;
}

Type parameters

Name	Constraint
N
F
V
KV
OnSubmitCallback	(args: any[]) => any

Properties

Name	Type	Optional	Description
name	N	false	Name of the form
fields	FieldValuesAndErrors	false	An object containing all the fields' values and
if they are valid.
hasErrors	boolean	false	true if any of the fields contains an error.
To determine the error status of each fields individually,
have a look at the fields
handleChange	ChangeHandler<F, KV>	false	Call it to respond to input changes.
handleSubmit	(event?: FormEvent | undefined) => ReturnType	false	Invokes onSubmit. Before that, it runs all field
validations, and if any of them fails, a notification
is emitted with type validationErrors and a list of
failed validations.
loading	boolean	false	Tells if there is some async operation running in the form,
like sending data to server. Can be used to for example disable
the UI while something happens that we should wait for.
inputs	InputPropGenerators	false	A convinient way to connect input fields to certain values
in the form.
Instead of using handleChange and define
name, id type and value attributes individually
on each input elements,
you can use inputs to spread all the necessary props.
(For more, see the docs)
validators	V	false

---

FormProviderProps

interface FormProviderProps<T, N1, N2> {
    children: ReactElement<any, string | (props: any) => ReactElement<any, string | any | (new (props: any) => Component<any, any, any>)> ... | new (props: any) => Component<any, any, any>>;
    initialState: T;
    validators?: AllValidators<T> | undefined<T>;
    onSubmit?: SubmitFunction<T, N2, Form<T>, keyof T> | undefined<T, N2, Form<T>, keyof T>;
    onNotify?: N1 | undefined;
}

Type parameters

Name
T
N1
N2

Properties

Name	Type	Optional	Description
children	ReactElement<any, string | (props: any) => ReactElement<any, string | any | (new (props: any) => Component<any, any, any>)> ... | new (props: any) => Component<any, any, any>>	false	You can utilize useForm anywhere from this element down the tree.
initialState	T	false	Give the initial state of the forms.
validators	AllValidators | undefined	true	The validators for the forms. Mirrors the structure of initialState.
onSubmit	SubmitFunction<T, N2, Form, keyof T> | undefined<T, N2, Form, keyof T>	true
onNotify	N1 | undefined	true

---

FieldValueAndError

interface FieldValueAndError<V> {
    value: V;
    error?: boolean | undefined;
}

Type parameters

Name
V

Properties

Name	Type	Optional	Description
value	V	false	The field's value.
error	boolean | undefined	true	true if the field value is invalid.

---

GeneratedProps

interface GeneratedProps<T, F, N extends keyof F> {
    id: N;
    name: N;
    value: F[N];
    type: T extends "datetimeLocal" ? "datetime-local" : T;
    onChange: bivarianceHack;
}

Type parameters

Name	Constraint
T
F
N	keyof F

Properties

Name	Type	Optional
id	N	false
name	N	false
value	F[N]	false
type	T extends "datetimeLocal" ? "datetime-local" : T	false
onChange	bivarianceHack	false

---

ValidateParams

interface ValidateParams<F> {
    fields: Partial<F>;
    validators: Validators<F>;
    validations?: string[];
    form?: F | undefined;
    submitting?: Boolean | undefined;
}

Type parameters

Name
F

Properties

Name	Type	Optional
fields	Partial	false
validators	Validators	false
validations	string[]	true
form	F | undefined	true
submitting	Boolean | undefined	true

Types

SubmitCallback

type SubmitCallback<N, F, T = any> = (submitParams: { name?: N | undefined; fields: F; setLoading: Dispatch<SetStateAction<boolean>>; notify: NotifyCallback<F, SubmitNotificationType>; }) => T;

Type parameters

Name	Default
N
F
T	any

Type

(submitParams: { name?: N | undefined; fields: F; setLoading: Dispatch<SetStateAction>; notify: NotifyCallback<F, SubmitNotificationType>; }) => T

---

FieldValues

type FieldValues<F = {}> = {
    [K extends keyof F]: F[K]
};

Type parameters

Name	Default
F	{}

Type

{ [K extends keyof F]: F[K] }

---

FieldValuesAndErrors

type FieldValuesAndErrors<F = {}> = {
    [K extends keyof F]: FieldValueAndError<F[K]>
};

Type parameters

Name	Default
F	{}

Type

{ [K extends keyof F]: FieldValueAndError<F[K]> }

---

InputTypes

type InputTypes = "text" | "radio" | "email" | "password" | "search" | "color" | "tel" | "url" | "submit" | "date" | "time" | "week" | "month" | "datetimeLocal" | "number" | "range" | "checkbox" | "select";

Type

"text" | "radio" | "email" | "password" | "search" | "color" | "tel" | "url" | "submit" | "date" | "time" | "week" | "month" | "datetimeLocal" | "number" | "range" | "checkbox" | "select"

---

GenericObject

type GenericObject = {
    [key: string]: any;
};

Type

{ [key: string]: any; }

---

GeneratePropsFunc

type GeneratePropsFunc<T, F, N extends keyof F, R, P = { name: N; value: F[N]; error: boolean; }> = (props: P) => P & R;

Type parameters

Name	Constraint	Default
T
F
N	keyof F
R
P		{ name: N; value: F[N]; error: boolean; }

Type

(props: P) => P & R

---

InputPropGenerator

type InputPropGenerator<T, F, N extends keyof F, G extends (args: any[]) => any = GeneratePropsFunc<T, F, N, {}>> = (name: N, options?: { value: T extends "checkbox" | "select" ? string : never; generateProps: G; } | undefined) => GeneratedProps<T, F, N> | ReturnType<G>;

Type parameters

Name	Constraint	Default
T
F
N	keyof F
G	(args: any[]) => any	GeneratePropsFunc<T, F, N, {}>

Type

(name: N, options?: { value: T extends "checkbox" | "select" ? string : never; generateProps: G; } | undefined) => GeneratedProps<T, F, N> | ReturnType

---

InputPropGenerators

type InputPropGenerators<F> = {
    [K extends InputTypes]: InputPropGenerator<K, F, keyof F>
};

Type parameters

Name
F

Type

{ [K extends InputTypes]: InputPropGenerator<K, F, keyof F> }

---

SubmitError

type SubmitError = "submitError";

Type

"submitError"

---

ValidationErrors

type ValidationErrors = "validationErrors";

Type

"validationErrors"

---

SubmitNotificationType

type SubmitNotificationType = "submitError" | "submitSuccess";

Type

"submitError" | "submitSuccess"

---

NotificationType

type NotificationType = "validationErrors" | SubmitNotificationType;

Type

"validationErrors" | SubmitNotificationType

---

Reason

type Reason<S, F> = Reason<S, F>;

Type parameters

Name
S
F

Type

Reason<S, F>

---

NotifyCallback

type NotifyCallback<F, S extends NotificationType = NotificationType> = (type: S, reason?: Reason<S, F> | undefined<S, F>) => void;

Type parameters

Name	Constraint	Default
F
S	NotificationType	NotificationType

Type

(type: S, reason?: Reason<S, F> | undefined<S, F>) => void

---

Errors

type Errors<T> = {
    [K extends keyof T]: boolean
};

Type parameters

Name
T

Type

{ [K extends keyof T]: boolean }

---

Validators

type Validators<T> = (fields: T, submitting: boolean) => Errors<T>;

Type parameters

Name
T

Type

(fields: T, submitting: boolean) => Errors

Variables

default

Context that holds the forms

var default: {}<any>;

Type

{}