Elderform
Form handling without tears and predictable form state based on defined parameters. Elderform gives you everything you need to create robust forms and stays out of your way.
Features
- Async validation
- Create reusable forms
- Predictable form state
- Cancel form submission
- Full typescript support
- Lazy schema initialisation
- Tiny: fully packed in just ~5kb
- Framework agnostic
- Ships with sensible defaults for form handling
-
No more "how do I prevent multple submission while currently submitting"
Quick start
pnpm add xstate elderform
import * as z from 'zod';
import {createForm, object} from 'elderform';
const form = createForm({
schema: object({
name: val => z.string().parse(val),
}),
onSubmit: () => {
return Promise.resolve();
},
});
form.subscribe((state) => {
...
});
form.submit();
API
createForm(config)
config(object) - config object from creating the form state machine (see below)
Config:
schema?(boolean | object) - object containing functions orfalseto disable schema validation- The schema by default is immutable, you can't change the schema after setting it initialy or by calling
form.set("schema", {...}).
- The schema by default is immutable, you can't change the schema after setting it initialy or by calling
initialValues?(object) - initial form valuesonSubmit(values: object)- an async function that handles form submission
Returns:
An object which providess
form.submit((...ignore?: string[]) => void) - a function to submit the formform.cancel(() => void) - function to cancel the current form submissionform.subscribe((stateListener) => () => void) - a state listener with the current state of the form (see below for stateListener)form.__service- the base service (xstate interpreter), made available for library authors to creating wrappers for frameworksform.validate((field) => void) - function to validate given fieldform.set((name, value) => void) - function to set values fordata,error,errors,schemaorvaluesform.setField((name, value) => void) - function to set value of given fields in schemaform.spawn((name, validator) => void) - An escape hatch to spawn new fields not specified in the schema. (useful for creating dynamic forms)-
should be used with caution, doing this would make the form unpredictable, given you can no longer reason about your form based on the defined schema.
-
form.kill((name) => void) - A function to kill aspawnedfield
State Listener
form.subscribe(currentState, handlers)
currentState
-
state - Form State
-
Boolean flags derived from form
stateisIdleisValidatingisSubmittingisSuccesssubmitted- similar toisSuccessisErrorvalidatedWithErrors- derived from validating state and if errors property is not emptysubmittedWithoutError- derived from submitted state and if errors property is emptysubmittedWithError- derived from error state and if errors property is not empty.
-
Others
values(object) - form values (Defaults to an empty object)data(TData | null)- Defaults to
undefined - The last data returned from successfully submission
- Defaults to
error(TError | null)- Defaults to
undefined - The error object last from submission, if an error was thrown
- Defaults to
errors(Map<string, TErrors>) - a map containing errors for each field after validationdataUpdatedAt(number) - The timestamp for when the form most recently submitted successfully and returned data (Defaults to0)errorUpdatedAt(number) - The timestamp for when the form most recently failed to submit successfully and returned error (Defaults to0).
handlers
An object containing handlers for each field present in the schema
| key | type |
|---|---|
state |
Field State |
error |
TErrors |
value |
T or null |
set or setWithValidate |
(value: T) => void |
validate |
() => void |
Form State
idle- when the form isn't actively performing any operationvalidating- when the defined schema is being validatedsubmitting- when the is being submittedsubmitted- if the form submitted successfully without any errorerror- if the submission attempt resulted in an error. The error is contained in the corresponding error property
Field State
idle- when the field is not performing any actionvalidating- when the field is validatingsuccess- if the field was validated successfullyfailed- if the field failed validation
314 Dec 26, 2022
2.6k Dec 15, 2022
279 Nov 1, 2022
2.8k Mar 29, 2021
584 Jan 2, 2023
2.6k Dec 23, 2022
23 Dec 17, 2022
49 May 13, 2022
3 Apr 4, 2022
2 Jul 1, 2022