💪🏽 Form creation made easy, backed by state machines
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.
No more "how do I prevent multple submission while currently submitting"
pnpm add xstate elderform
import * as z from 'zod';
import {createForm} from 'elderform';
const form = createForm({
initialValues: {
age: 10,
name: {
last: '',
first: '',
middle: '',
},
mother: {
name: {
last: '',
first: '',
middle: '',
},
},
},
onSubmit: () => {
return Promise.resolve();
},
});
form.spawn('name', null, v => zod.string().parse(v))
form.subscribe((state) => {
...
});
form.submit();
createForm(config)
config
(object) - config object from creating the form state machine (see below)initialValues?
(object) - initial form valuesonSubmit(values: object)
- an async function that handles form submissionAn object which provides
submit
((...ignore?: string[]) => void) - a function to submit the formreset
- a function to reset the form state to its initial statecancel
(() => void) - function to cancel either the form validation or the current form submissionsubmitAsync
- async version of submit and resolves with the submission resultset
- ((name, value) => void) - a function to set the value for any given fieldsubscribe
((stateListener) => () => void) - a state listener with the current state of the form (see below for stateListener)__service
- the base service (xstate interpreter), made available for library authors to creating wrappers for frameworksvalidate
((field, value?) => void) - function to validate given fieldspawn
((name, value, validator) => void) - An escape hatch to spawn new fields not specified in the schema. (useful for creating dynamic forms)kill
((name) => void) - A function to kill a spawned
fieldsubscribe(
currentState)
currentState
state - Form State
Boolean flags derived from form state
value
isIdle
isValidating
isSubmitting
submitted
isError
isSuccess
- similar to submitted
Others
values
(object) - form values (Defaults to an empty object)data
(TData | null)
undefined
error
(TError | null)
undefined
errors
(Record<string, TErrors>) - an object of errors for each field after validationdataUpdatedAt
(number) -
The timestamp for when the form most recently submitted successfully and returned data (Defaults to 0
)errorUpdatedAt
(number) -
The timestamp for when the form most recently failed to submit successfully and returned error (Defaults to 0
).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 propertyidle
- when the field is not performing any actionvalidating
- when the field is validatingsuccess
- if the field was validated successfullyfailed
- if the field failed validation