npm i form-atoms jotai

Features

Quick start

import{fieldAtom,useInputField,formAtom,useForm}from"form-atoms";constnameFormAtom=formAtom({name:{first:fieldAtom({value:""}),last:fieldAtom({value:""}),},});functionForm(){const{ fieldAtoms, submit}=useForm(nameFormAtom);return(<formonSubmit={submit((values)=>{console.log(values);})}><Fieldlabel="First name"atom={fieldAtoms.name.first}/><Fieldlabel="Last name"atom={fieldAtoms.name.last}/></form>);}functionField({ label, atom}){constfield=useInputField(atom);return(<label><span>{label}</span><input{...field.props}/></label>);}

Concepts

Table of contents

Recipes

Projects usingform-atoms

Field atoms

fieldAtom()

Arguments

FieldAtomConfig

typeFieldAtomConfig<Value>={/**   * Optionally provide a name for the field that will be added   * to any attached `<input>`, `<select>`, or `<textarea>` elements   */name?:string;/**   * The initial value of the field   */value:Value;/**   * The initial touched state of the field   */touched?:boolean;/**   * Transform the value of the field each time `setValue` is   * called, before validation and when the field is initialized.   * Optionally subscribe to other atoms via the `get` function.   */preprocess?:(value:Value,get:Getter)=>Value;/**   * A function that validates the value of the field any time   * one of its atoms changes. It must either return an array of   * string error messages or undefined. If it returns undefined,   * the validation is "skipped" and the current errors in state   * are retained.   */validate?:(state:{/**     * A Jotai getter that can read other atoms     */get:Getter;/**     * The current value of the field     */value:Value;/**     * The dirty state of the field     */dirty:boolean;/**     * The touched state of the field     */touched:boolean;/**     * The event that caused the validation. Either:     *     * - `"change"` - The value of the field has changed     * - `"touch"` - The field has been touched     * - `"blur"` - The field has been blurred     * - `"submit"` - The form has been submitted     * - `"user"` - A user/developer has triggered the validation     */event:ValidateOn;})=>void|string[]|Promise<void|string[]>;};

Returns

typeFieldAtom<Value>=Atom<{/**   * An atom containing the field's name   */name:WritableAtom<string|undefined,[string|undefined|typeofRESET],void>;/**   * An atom containing the field's value   */value:WritableAtom<Value,[Value|typeofRESET|((prev:Value)=>Value)],void>;/**   * An atom containing the field's touched status   */touched:WritableAtom<boolean,[boolean|typeofRESET|((prev:boolean)=>boolean)],void>;/**   * An atom containing the field's dirty status   */dirty:Atom<boolean>;/**   * A write-only atom for validating the field's value   */validate:WritableAtom<null,[]|[ValidateOn],void>;/**   * An atom containing the field's validation status   */validateStatus:WritableAtom<ValidateStatus,[ValidateStatus],void>;/**   * An atom containing the field's validation errors   */errors:WritableAtom<string[],[string[]|((value:string[])=>string[])],void>;/**   * A write-only atom for resetting the field atoms to their   * initial states.   */reset:WritableAtom<null,[],void>;/**   * An atom containing a reference to the `HTMLElement` the field   * is bound to.   */ref:WritableAtom<HTMLInputElement|HTMLTextAreaElement|HTMLSelectElement|null,[|HTMLInputElement|HTMLTextAreaElement|HTMLSelectElement|null|((value:|HTMLInputElement|HTMLTextAreaElement|HTMLSelectElement|null,)=>HTMLInputElement|HTMLTextAreaElement|HTMLSelectElement|null),],void>;}>;

⇗ Back to top

useField()

Arguments

Returns

typeUseFieldAtom<Value>={/**   * Actions for managing the state of the field   */actions:UseFieldActions<Value>;/**   * The current state of the field   */state:UseFieldState<Value>;};

⇗ Back to top

useInputField()

Arguments

Returns

typeUseInputField<TypeextendsReact.HTMLInputTypeAttribute,ValueextendsInputFieldValueForType<Type>=InputFieldValueForType<Type>,>={/**   * `<input>` props for the field   */props:UseInputFieldProps<Type>;/**   * Actions for managing the state of the field   */actions:UseFieldActions<Value>;/**   * The current state of the field   */state:UseFieldState<Value>;};

⇗ Back to top

useInputFieldProps()

Arguments

Returns

typeUseInputFieldProps<TypeextendsReact.HTMLInputTypeAttribute>={/**   * The name of the field if there is one   */name:string|undefined;/**   * The value of the field   */value:TypeextendsDateType    ?string    :TypeextendsNumberType      ?number|string      :TypeextendsFileType        ?undefined        :string;/**   * The type of the field   *   *@default "text"   */type:Type;/**   * A WAI-ARIA property that tells a screen reader whether the   * field is invalid   */"aria-invalid":boolean;/**   * A React callback ref that is used to bind the field atom to   * an `<input>` element so that it can be read and focused.   */ref:React.RefCallback<HTMLInputElement>;onBlur(event:React.FormEvent<HTMLInputElement>):void;onChange(event:React.ChangeEvent<HTMLInputElement>):void;};

⇗ Back to top

useTextareaField()

Arguments

Returns

typeUseTextareaField<Valueextendsstring>={/**   * `<input>` props for the field   */props:UseTextareaFieldProps<Value>;/**   * Actions for managing the state of the field   */actions:UseFieldActions<Value>;/**   * The current state of the field   */state:UseFieldState<Value>;};

⇗ Back to top

useTextareaFieldProps()

Arguments

Returns

typeUseTextareaFieldProps<Valueextendsstring>={/**   * The name of the field if there is one   */name:string|undefined;/**   * The value of the field   */value:Value;/**   * A WAI-ARIA property that tells a screen reader whether the   * field is invalid   */"aria-invalid":boolean;/**   * A React callback ref that is used to bind the field atom to   * an `<input>` element so that it can be read and focused.   */ref:React.RefCallback<HTMLTextAreaElement>;onBlur(event:React.FormEvent<HTMLTextAreaElement>):void;onChange(event:React.ChangeEvent<HTMLTextAreaElement>):void;};

⇗ Back to top

useSelectField()

Arguments

Returns

typeUseSelectField<Valueextendsstring,MultipleextendsReadonly<boolean>=false,>={/**   * `<input>` props for the field   */props:UseSelectFieldProps<Value,Multiple>;/**   * Actions for managing the state of the field   */actions:UseFieldActions<Multipleextendstrue ?Value[] :Value>;/**   * The current state of the field   */state:UseFieldState<Multipleextendstrue ?Value[] :Value>;};

⇗ Back to top

useSelectFieldProps()

Arguments

Returns

typeUseSelectFieldProps<Valueextendsstring,MultipleextendsReadonly<boolean>=false,>={/**   * The name of the field if there is one   */name:string|undefined;/**   * The value of the field   */value:Multipleextendstrue ?Value[] :Value;/**   * Whether the field is a multiple select   */multiple?:Multiple;/**   * A WAI-ARIA property that tells a screen reader whether the   * field is invalid   */"aria-invalid":boolean;/**   * A React callback ref that is used to bind the field atom to   * an `<input>` element so that it can be read and focused.   */ref:React.RefCallback<HTMLSelectElement>;onBlur(event:React.FormEvent<HTMLSelectElement>):void;onChange(event:React.ChangeEvent<HTMLSelectElement>):void;};

⇗ Back to top

useFieldState()

Arguments

Returns

typeUseFieldState<Value>={/**   * The value of the field   */value:ExtractAtomValue<ExtractAtomValue<FieldAtom<Value>>["value"]>;/**   * The touched state of the field   */touched:ExtractAtomValue<ExtractAtomValue<FieldAtom<Value>>["touched"]>;/**   * The dirty state of the field. A field is "dirty" if it's value has   * been changed.   */dirty:ExtractAtomValue<ExtractAtomValue<FieldAtom<Value>>["dirty"]>;/**   * The validation status of the field   */validateStatus:ExtractAtomValue<ExtractAtomValue<FieldAtom<Value>>["validateStatus"]>;/**   * The error state of the field   */errors:ExtractAtomValue<ExtractAtomValue<FieldAtom<Value>>["errors"]>;};

⇗ Back to top

useFieldActions()

Arguments

Returns

typeUseFieldActions<Value>={/**   * A function that validates the field's value with a `"user"` validation   * event.   */validate():void;/**   * A function for changing the value of a field. This will trigger a `"change"`   * validation event.   *   *@param {Value} value - The new value of the field   */setValue(value:ExtractAtomArgs<ExtractAtomValue<FieldAtom<Value>>["value"]>[0],):void;/**   * A function for changing the touched state of a field. This will trigger a   * `"touch"` validation event.   *   *@param {boolean} touched - The new touched state of the field   */setTouched(touched:ExtractAtomArgs<ExtractAtomValue<FieldAtom<Value>>["touched"]>[0],):void;/**   * A function for changing the error state of a field   *   *@param {string[]} errors - The new error state of the field   */setErrors(errors:ExtractAtomArgs<ExtractAtomValue<FieldAtom<Value>>["errors"]>[0],):void;/**   * Focuses the field atom's `<input>`, `<select>`, or `<textarea>` element   * if there is one bound to it.   */focus():void;/**   * Resets the field atom to its initial state.   */reset():void;};

⇗ Back to top

useFieldInitialValue()

Arguments

⇗ Back to top

useFieldValue()

Arguments

Returns

typeUseFieldValue<Value>=Value;

⇗ Back to top

useFieldErrors()

Arguments

Returns

typeUseFieldErrors<Value>=UseFieldState<Value>["errors"];

⇗ Back to top

Form atoms

formAtom()

Arguments

FormFields

typeFormFields={[key:string|number]:|FieldAtom<any>|FormFields|FormFields[]|FieldAtom<any>[];};

Returns

typeFormAtom<FieldsextendsFormFields>=Atom<{/**   * An atom containing an object of nested field atoms   */fields:WritableAtom<Fields,Fields|typeofRESET|((prev:Fields)=>Fields),void>;/**   * An read-only atom that derives the form's values from   * its nested field atoms.   */values:Atom<FormFieldValues<Fields>>;/**   * An read-only atom that derives the form's errors from   * its nested field atoms.   */errors:Atom<FormFieldErrors<Fields>>;/**   * A read-only atom that returns `true` if any of the fields in   * the form are dirty.   */dirty:Atom<boolean>;/**   * A read-only atom derives the touched state of its nested field atoms.   */touchedFields:Atom<TouchedFields<Fields>>;/**   * A write-only atom that resets the form's nested field atoms   */reset:WritableAtom<null,void>;/**   * A write-only atom that validates the form's nested field atoms   */validate:WritableAtom<null,void|ValidateOn>;/**   * A read-only atom that derives the form's validation status   */validateStatus:Atom<ValidateStatus>;/**   * A write-only atom for submitting the form   */submit:WritableAtom<null,(values:FormFieldValues<Fields>)=>void|Promise<void>>;/**   * A read-only atom that reads the number of times the form has   * been submitted   */submitCount:Atom<number>;/**   * An atom that contains the form's submission status   */submitStatus:WritableAtom<SubmitStatus,SubmitStatus>;}>;

⇗ Back to top

useForm()

Arguments

Returns

typeUseFormAtom<FieldsextendsFormFields>={/**   * An object containing the values of a form's nested field atoms   */fieldAtoms:Fields;/**   * A function for handling form submissions.   *   *@param handleSubmit - A function that is called with the form's values   *   when the form is submitted   */submit(handleSubmit:(values:FormFieldValues<Fields>)=>void|Promise<void>,):(e?:React.FormEvent<HTMLFormElement>)=>void;/**   * A function that validates the form's nested field atoms with a   * `"user"` validation event.   */validate():void;/**   * A function that resets the form's nested field atoms to their   * initial states.   */reset():void;};

⇗ Back to top

useFormState()

Arguments

Returns

typeUseFormState<FieldsextendsFormFields>={/**   * An object containing the form's nested field atoms   */fieldAtoms:Fields;/**   * An object containing the values of a form's nested field atoms   */values:FormFieldValues<Fields>;/**   * An object containing the errors of a form's nested field atoms   */errors:FormFieldErrors<Fields>;/**   * `true` if any of the fields in the form are dirty.   */dirty:boolean;/**   * An object containing the touched state of the form's nested field atoms.   */touchedFields:TouchedFields<Fields>;/**   * The number of times a form has been submitted   */submitCount:number;/**   * The validation status of the form   */validateStatus:ValidateStatus;/**   * The submission status of the form   */submitStatus:SubmitStatus;};

⇗ Back to top

useFormActions()

Arguments

Returns

typeUseFormActions<FieldsextendsFormFields>={/**   * A function for adding/removing fields from the form.   *   *@param fields - An object containing the form's nested field atoms or   *   a callback that receives the current fields and returns the next   *   fields.   */updateFields(fields:ExtractAtomArgs<ExtractAtomValue<FormAtom<Fields>>["fields"]>[0],):void;/**   * A function for handling form submissions.   *   *@param handleSubmit - A function that is called with the form's values   *   when the form is submitted   */submit(handleSubmit:(values:FormFieldValues<Fields>)=>void|Promise<void>,):(e?:React.FormEvent<HTMLFormElement>)=>void;/**   * A function that validates the form's nested field atoms with a   * `"user"` validation event.   */validate():void;/**   * A function that resets the form's nested field atoms to their   * initial states.   */reset():void;};

⇗ Back to top

useFormValues()

Arguments

Returns

typeUseFormValues<FieldsextendsFormFields>=FormFieldValues<Fields>;

⇗ Back to top

useFormErrors()

Arguments

Returns

typeUseFormErrors<FieldsextendsFormFields>=FormFieldErrors<Fields>;

⇗ Back to top

useFormStatus()

Arguments

Returns

typeUseFormStatus={/**   * The validation status of the form   */validateStatus:ValidateStatus;/**   * The submission status of the form   */submitStatus:SubmitStatus;};

⇗ Back to top

useFormSubmit()

Arguments

Returns

typeUseFormSubmit<FieldsextendsFormFields>={(values:(value:FormFieldValues<Fields>)=>void|Promise<void>,):(e?:React.FormEvent<HTMLFormElement>)=>void;};

⇗ Back to top

Components

<Form>

Props

⇗ Back to top

<InputField>

Props

⇗ Back to top

<TextareaField>

Props

⇗ Back to top

<SelectField>

Props

⇗ Back to top

<Field>

Props

⇗ Back to top

Utilities

walkFields()

Arguments

Returns

void

⇗ Back to top

Utility types

FormValues

constnameForm=formAtom({name:fieldAtom({value:""}),});typeNameFormValues=FormValues<typeofnameForm>;

⇗ Back to top

FormErrors

constnameForm=formAtom({name:fieldAtom({value:""}),});typeNameFormErrors=FormErrors<typeofnameForm>;

⇗ Back to top

form-atoms/valibot

createValibotValidator()

import{formAtom,fieldAtom}from"form-atoms";import{createValibotValidator}from"form-atoms/valibot";import{parseAsync,string,pipe,minLength}from"valibot";constvalibotValidate=createValibotValidator(parseAsync);//...constnameForm=formAtom({name:fieldAtom({validate:valibotValidate(pipe(string(),minLength(3,"uh oh")),{on:"submit",when:"dirty",}),}),});

form-atoms/zod

zodValidate()

import{z}from"zod";import{formAtom,fieldAtom}from"form-atoms";import{zodValidate}from"form-atoms/zod";constschema=z.object({name:z.string().min(3),});constnameForm=formAtom({name:fieldAtom({validate:zodValidate(schema.shape.name,{on:"submit",when:"dirty",}),}),});

Arguments

ZodValidateConfig

typeZodValidateConfig={/**   * The event or events that triggers validation.   */on?:ZodValidateOn|ZodValidateOn[];/**   * Validate if the field is:   * - `touched`   * - `dirty`   */when?:"touched"|"dirty"|("touched"|"dirty")[];/**   * Format the error message returned by the validator.   *   *@param error - A ZodError object   */formatError?:(error:ZodError)=>string[];};

⇗ Back to top

Wait, it's all atoms?

⇗ Back to top

LICENSE