Package @reatom/form

@reatom/form

Interfaces

BaseFormOptions

Defined in: form/reatomForm.ts:178

Extended by

FormOptionsWithSchema
FormOptionsWithoutSchema

Properties

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomForm.ts:194

Defines the default reset behavior of the validation state during async validation for all fields.

Default

false

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomForm.ts:203

Defines the default reset behavior of the validation state on field change for all fields. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

name?

optional name: string

Defined in: form/reatomForm.ts:179

resetOnSubmit?

optional resetOnSubmit: boolean

Defined in: form/reatomForm.ts:186

Should reset the state after success submit?

Default

false

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomForm.ts:219

Defines if the validation should be triggered on the field blur by default for all fields.

Default

false

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomForm.ts:211

Defines if the validation should be triggered with every field change by default for all fields.

Default

false

FieldAtom()

Defined in: form/reatomField.ts:104

Base changeable state container.

Atom is the core primitive for storing and updating mutable state in Reatom. It can be called to retrieve its current state or update it with a new value or update function.

Extends

FieldLikeAtom<State>

Type Parameters

State

State = any

The type of state stored in the atom

Value

Value = State

FieldAtom(…params): State

Defined in: form/reatomField.ts:104

Call the atom to either read or update its state.

Parameters

params

…[]

Parameters to pass to the atom

Returns

State

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

FieldLikeAtom.__reatom

__reatomField

__reatomField: true

Defined in: form/reatomField.ts:101

Inherited from

FieldLikeAtom.__reatomField

change

change: Action<[Value], Value>

Defined in: form/reatomField.ts:112

Action for handling field changes, accepts the “value” parameter and applies it to toState option.

disabled

disabled: BooleanAtom

Defined in: form/reatomField.ts:130

Atom that defines if the field is disabled

elementRef

elementRef: Atom<FieldElementRef | undefined>

Defined in: form/reatomField.ts:133

Atom with the reference to the field element.

extend

extend: Extend<FieldAtom<State, Value>>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

FieldLikeAtom.extend

focus

focus: FocusAtom

Defined in: form/reatomField.ts:115

Atom of an object with all related focus statuses.

initState

initState: Atom<State>

Defined in: form/reatomField.ts:118

The initial state of the atom.

options

options: RecordAtom<{ keepErrorDuringValidating: boolean | undefined; keepErrorOnChange: boolean | undefined; shouldValidate: boolean | undefined; validateOnBlur: boolean | undefined; validateOnChange: boolean | undefined; }>

Defined in: form/reatomField.ts:135

reset

reset: Action<[] | [State], void>

Defined in: form/reatomField.ts:121

Action to reset the state, the value, the validation, and the focus.

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Subscribe to state changes, with the first call happening immediately. When a subscriber is added, the callback is immediately invoked with the current state. After that, it’s called whenever the atom’s state changes.

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

FieldLikeAtom.subscribe

validation

validation: ValidationAtom

Defined in: form/reatomField.ts:124

Atom of an object with all related validation statuses.

value

value: Atom<Value>

Defined in: form/reatomField.ts:127

Writable atom with the “value” data, computed by the fromState option

Methods

set()

Call Signature

set(update): State

Defined in: core/atom.ts:115

Update the atom’s state using a function that receives the previous state

Parameters

update

(state) => State

Function that takes the current state and returns a new state

Returns

State

The new state value

Inherited from

FieldLikeAtom.set

Call Signature

set(…params): State

Defined in: core/atom.ts:123

Set the atom’s state to a new value

Parameters

params

…[State]

Returns

State

The new state value

Inherited from

FieldLikeAtom.set

FieldElementRef

Defined in: form/reatomField.ts:96

Properties

focus()

focus: (options?) => void

Defined in: form/reatomField.ts:97

Parameters

options?

preventScroll?

boolean

Returns

void

FieldError

Defined in: form/reatomField.ts:58

Extends

FieldErrorBody<Meta>

Extended by

FieldSetFieldError

Type Parameters

Properties

message

message: string

Defined in: form/reatomField.ts:48

The message of the error useful for a user.

Inherited from

FieldErrorBody.message

meta?

optional meta: Rec<Meta>

Defined in: form/reatomField.ts:53

The record with arbitrary information about the error like minimum chars, upper bound of a number, etc.

Inherited from

FieldErrorBody.meta

source

source: FieldErrorSource

Defined in: form/reatomField.ts:63

The type of an error source. The value will be validation if the error occurred due to the validate function.

FieldErrorBody

Defined in: form/reatomField.ts:46

Extended by

FieldError

Type Parameters

Properties

message

message: string

Defined in: form/reatomField.ts:48

The message of the error useful for a user.

meta?

optional meta: Rec<Meta>

Defined in: form/reatomField.ts:53

The record with arbitrary information about the error like minimum chars, upper bound of a number, etc.

FieldFocus

Defined in: form/reatomField.ts:35

Properties

active

active: boolean

Defined in: form/reatomField.ts:37

The field is focused.

dirty

dirty: boolean

Defined in: form/reatomField.ts:40

The field state is not equal to the initial state.

touched

touched: boolean

Defined in: form/reatomField.ts:43

The field has ever gained and lost focus.

FieldLikeAtom()

Defined in: form/reatomField.ts:100

Base changeable state container.

Atom is the core primitive for storing and updating mutable state in Reatom. It can be called to retrieve its current state or update it with a new value or update function.

Extends

Atom<State>

Extended by

FieldAtom

Type Parameters

State

State = any

The type of state stored in the atom

FieldLikeAtom(…params): State

Defined in: form/reatomField.ts:100

Call the atom to either read or update its state.

Parameters

params

…[]

Parameters to pass to the atom

Returns

State

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

Atom.__reatom

__reatomField

__reatomField: true

Defined in: form/reatomField.ts:101

extend

extend: Extend<FieldLikeAtom<State>>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

Atom.extend

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

Atom.subscribe

Methods

set()

Call Signature

set(update): State

Defined in: core/atom.ts:115

Update the atom’s state using a function that receives the previous state

Parameters

update

(state) => State

Function that takes the current state and returns a new state

Returns

State

The new state value

Inherited from

Atom.set

Call Signature

set(…params): State

Defined in: core/atom.ts:123

Set the atom’s state to a new value

Parameters

params

…[State]

Returns

State

The new state value

Inherited from

Atom.set

FieldOptions

Defined in: form/reatomField.ts:188

Extended by

FormFieldOptions

Type Parameters

State

State = any

Value

Value = State

Properties

disabled?

optional disabled: boolean

Defined in: form/reatomField.ts:238

Defines if the field is disabled by default.

Default

false

elementRef?

optional elementRef: FieldElementRef

Defined in: form/reatomField.ts:241

Defines a default element reference accosiated with the field.

filter()?

optional filter: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:194

The callback to filter “value” changes (from the ‘change’ action). It should return ‘false’ to skip the update. By default, it always returns true.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

fromState()?

optional fromState: (state, self) => Value

Defined in: form/reatomField.ts:200

The callback to compute the “value” data from the “state” data. By default, it returns the “state” data without any transformations.

Parameters

state

State

self

FieldAtom<State, Value>

Returns

Value

isDirty()?

optional isDirty: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:225

The callback used to determine whether the “value” has changed. By default, it utilizes isDeepEqual from reatom/utils.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomField.ts:248

Defines the reset behavior of the validation state during async validation.

Default

false

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomField.ts:256

Defines the reset behavior of the validation state on field change. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

name?

optional name: string

Defined in: form/reatomField.ts:228

The name of the field and all related atoms and actions.

toState()?

optional toState: (value, self) => State

Defined in: form/reatomField.ts:219

The callback to transform the “state” data from the “value” data from the change action. By default, it returns the “value” data without any transformations.

It’s also possible to abort the computation and left the state unchaged by throwing abort error inside the callback

Parameters

value

Value

self

FieldAtom<State, Value>

Returns

State

Example

const numberField = reatomField(0, {
    fromState: (state) => state.toString(),
    toState: (value: string) => {
      const parsed = Number(value)
      return isNaN(parsed) ? throwAbort() : parsed
    },
  })

validate?

optional validate: FieldValidateOption<State, Value> | StandardSchemaV1<State, State>

Defined in: form/reatomField.ts:231

The callback to validate the field.

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomField.ts:270

Defines if the validation should be triggered on the field blur.

Default

false

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomField.ts:263

Defines if the validation should be triggered with every field change.

Default

false

FieldSet()

Defined in: form/reatomFieldSet.ts:65

Derived state container.

A computed atom automatically tracks dependencies and recalculates only when those dependencies change. The calculation is performed lazily, only when the computed value is read AND subscribed to.

Extends

ValidationlessFieldSet<T>

Type Parameters

T

T extends FormInitState

The type of derived state

FieldSet(…params): Deatomize

Defined in: form/reatomFieldSet.ts:65

Call the atom to either read or update its state.

Parameters

params

…[]

Parameters to pass to the atom

Returns

Deatomize

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

ValidationlessFieldSet.__reatom

extend

extend: Extend<FieldSet<T>>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

ValidationlessFieldSet.extend

fieldArraysList

fieldArraysList: Computed<FormFieldArrayAtom[]>

Defined in: form/reatomFieldSet.ts:50

Computed list of all the field arrays from the fields tree

Inherited from

ValidationlessFieldSet.fieldArraysList

fields

fields: FormFields<T>

Defined in: form/reatomFieldSet.ts:44

Fields from the init state

Inherited from

ValidationlessFieldSet.fields

fieldsList

fieldsList: Computed<FieldAtom<any, any>[]>

Defined in: form/reatomFieldSet.ts:47

Computed list of all the fields from the fields tree

Inherited from

ValidationlessFieldSet.fieldsList

focus

focus: Computed<FieldFocus>

Defined in: form/reatomFieldSet.ts:56

Atom with focus state of the fieldset, computed from all the fields in fieldsList

Inherited from

ValidationlessFieldSet.focus

init

init: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:59

Action to set initial values for each field or field array in the fieldset

Inherited from

ValidationlessFieldSet.init

reset

reset: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:62

Action to reset the state, the value, the validation, and the focus states.

Inherited from

ValidationlessFieldSet.reset

set

set: unknown

Defined in: core/atom.ts:72

Inherited from

ValidationlessFieldSet.set

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

ValidationlessFieldSet.subscribe

validation

validation: Computed<FieldSetValidation> & object

Defined in: form/reatomFieldSet.ts:72

Atom with validation state of the fieldset, computed from all the fields in fieldsList

Type Declaration

trigger

trigger: Action<[], FieldSetValidation> & AbortExt

Action to trigger fieldset validation.

FieldSetFieldError

Defined in: form/reatomFieldSet.ts:25

Extends

FieldError

Properties

field

field: FieldAtom

Defined in: form/reatomFieldSet.ts:26

message

message: string

Defined in: form/reatomField.ts:48

The message of the error useful for a user.

Inherited from

FieldError.message

meta?

optional meta: Rec<any>

Defined in: form/reatomField.ts:53

The record with arbitrary information about the error like minimum chars, upper bound of a number, etc.

Inherited from

FieldError.meta

source

source: FieldErrorSource

Defined in: form/reatomField.ts:63

The type of an error source. The value will be validation if the error occurred due to the validate function.

Inherited from

FieldError.source

FieldSetValidation

Defined in: form/reatomFieldSet.ts:29

Properties

errors

errors: FieldSetFieldError[]

Defined in: form/reatomFieldSet.ts:31

The list of field validation errors.

triggered

triggered: boolean

Defined in: form/reatomFieldSet.ts:34

The validation actuality status.

validating

validating: Promise<{ errors: FieldSetFieldError[]; }> | undefined

Defined in: form/reatomFieldSet.ts:37

The field async validation status

FieldValidation

Defined in: form/reatomField.ts:66

Properties

error

error: string | undefined

Defined in: form/reatomField.ts:68

Message of the first validation error, computed from errors atom

triggered

triggered: boolean

Defined in: form/reatomField.ts:71

The validation actuality status.

validating

validating: Promise<{ errors: FieldError<any>[]; }> | undefined

Defined in: form/reatomField.ts:74

The field async validation status.

FocusAtom()

Defined in: form/reatomField.ts:77

Base atom interface for other userspace implementations. This is the core interface that all atom-like objects implement, providing the foundation for Reatom’s reactivity system.

Extends

AtomLike<FieldFocus>

FocusAtom(…params): FieldFocus

Defined in: form/reatomField.ts:77

Call the atom to either read or update its state.

Parameters

params

…any[]

Parameters to pass to the atom

Returns

FieldFocus

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

AtomLike.__reatom

extend

extend: Extend<FocusAtom>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

AtomLike.extend

in

in: Action<[], FieldFocus>

Defined in: form/reatomField.ts:79

Action for handling field focus.

out

out: Action<[], FieldFocus>

Defined in: form/reatomField.ts:82

Action for handling field blur.

set

set: unknown

Defined in: core/atom.ts:72

Inherited from

AtomLike.set

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

AtomLike.subscribe

Form()

Defined in: form/reatomForm.ts:137

Derived state container.

A computed atom automatically tracks dependencies and recalculates only when those dependencies change. The calculation is performed lazily, only when the computed value is read AND subscribed to.

Extends

ValidationlessFieldSet<T>

Type Parameters

T

T extends FormInitState

The type of derived state

SchemaState

SchemaState = any

SubmitReturn

SubmitReturn = any

SubmitParams

SubmitParams extends any[] = any[]

Form(…params): Deatomize

Defined in: form/reatomForm.ts:137

Call the atom to either read or update its state.

Parameters

params

…[]

Parameters to pass to the atom

Returns

Deatomize

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

ValidationlessFieldSet.__reatom

extend

extend: Extend<Form<T, SchemaState, SubmitReturn, SubmitParams>>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

ValidationlessFieldSet.extend

fieldArraysList

fieldArraysList: Computed<FormFieldArrayAtom[]>

Defined in: form/reatomFieldSet.ts:50

Computed list of all the field arrays from the fields tree

Inherited from

ValidationlessFieldSet.fieldArraysList

fields

fields: FormFields<T>

Defined in: form/reatomFieldSet.ts:44

Fields from the init state

Inherited from

ValidationlessFieldSet.fields

fieldsList

fieldsList: Computed<FieldAtom<any, any>[]>

Defined in: form/reatomFieldSet.ts:47

Computed list of all the fields from the fields tree

Inherited from

ValidationlessFieldSet.fieldsList

focus

focus: Computed<FieldFocus>

Defined in: form/reatomFieldSet.ts:56

Atom with focus state of the fieldset, computed from all the fields in fieldsList

Inherited from

ValidationlessFieldSet.focus

init

init: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:59

Action to set initial values for each field or field array in the fieldset

Inherited from

ValidationlessFieldSet.init

reset

reset: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:62

Action to reset the state, the value, the validation, and the focus states.

Inherited from

ValidationlessFieldSet.reset

set

set: unknown

Defined in: core/atom.ts:72

Inherited from

ValidationlessFieldSet.set

submit

submit: SubmitAction<SubmitParams, SubmitReturn>

Defined in: form/reatomForm.ts:172

Submit async handler. It checks the validation of all the fields in fieldsList, calls the form’s validate options handler, and then the onSubmit options handler. Check the additional options properties of async action: https://reatom.dev/handbook/async/.

submitted

submitted: Computed<boolean>

Defined in: form/reatomForm.ts:175

Atom with submitted state of the form

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

ValidationlessFieldSet.subscribe

validation

validation: Computed<FieldSetValidation> & object & undefined extends SchemaState ? object : object

Defined in: form/reatomForm.ts:147

Atom with validation state of the form, computed from all the fields in fieldsList

Type Declaration

trigger

trigger: Action<[], Promise<undefined extends SchemaState ? Deatomize<FormFields<T>> : SchemaState>> & AsyncExt<[], any, Error | undefined> & AbortExt

Action to trigger form validation.

FormFieldOptions

Defined in: form/reatomForm.ts:46

Extends

FieldOptions<State, Value>

Type Parameters

State

State = any

Value

Value = State

Properties

disabled?

optional disabled: boolean

Defined in: form/reatomField.ts:238

Defines if the field is disabled by default.

Default

false

Inherited from

FieldOptions.disabled

elementRef?

optional elementRef: FieldElementRef

Defined in: form/reatomField.ts:241

Defines a default element reference accosiated with the field.

Inherited from

FieldOptions.elementRef

filter()?

optional filter: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:194

The callback to filter “value” changes (from the ‘change’ action). It should return ‘false’ to skip the update. By default, it always returns true.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

Inherited from

FieldOptions.filter

fromState()?

optional fromState: (state, self) => Value

Defined in: form/reatomField.ts:200

The callback to compute the “value” data from the “state” data. By default, it returns the “state” data without any transformations.

Parameters

state

State

self

FieldAtom<State, Value>

Returns

Value

Inherited from

FieldOptions.fromState

initState

initState: State

Defined in: form/reatomForm.ts:50

isDirty()?

optional isDirty: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:225

The callback used to determine whether the “value” has changed. By default, it utilizes isDeepEqual from reatom/utils.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

Inherited from

FieldOptions.isDirty

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomField.ts:248

Defines the reset behavior of the validation state during async validation.

Default

false

Inherited from

FieldOptions.keepErrorDuringValidating

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomField.ts:256

Defines the reset behavior of the validation state on field change. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

Inherited from

FieldOptions.keepErrorOnChange

name?

optional name: string

Defined in: form/reatomField.ts:228

The name of the field and all related atoms and actions.

Inherited from

FieldOptions.name

toState()?

optional toState: (value, self) => State

Defined in: form/reatomField.ts:219

The callback to transform the “state” data from the “value” data from the change action. By default, it returns the “value” data without any transformations.

It’s also possible to abort the computation and left the state unchaged by throwing abort error inside the callback

Parameters

value

Value

self

FieldAtom<State, Value>

Returns

State

Example

const numberField = reatomField(0, {
    fromState: (state) => state.toString(),
    toState: (value: string) => {
      const parsed = Number(value)
      return isNaN(parsed) ? throwAbort() : parsed
    },
  })

Inherited from

FieldOptions.toState

validate?

optional validate: FieldValidateOption<State, Value> | StandardSchemaV1<State, State>

Defined in: form/reatomField.ts:231

The callback to validate the field.

Inherited from

FieldOptions.validate

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomField.ts:270

Defines if the validation should be triggered on the field blur.

Default

false

Inherited from

FieldOptions.validateOnBlur

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomField.ts:263

Defines if the validation should be triggered with every field change.

Default

false

Inherited from

FieldOptions.validateOnChange

FormOptionsWithoutSchema

Defined in: form/reatomForm.ts:246

Extends

BaseFormOptions

Type Parameters

T

T extends FormInitState

SubmitReturn

SubmitReturn

SubmitParams

SubmitParams extends any[]

Properties

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomForm.ts:194

Defines the default reset behavior of the validation state during async validation for all fields.

Default

false

Inherited from

BaseFormOptions.keepErrorDuringValidating

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomForm.ts:203

Defines the default reset behavior of the validation state on field change for all fields. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

Inherited from

BaseFormOptions.keepErrorOnChange

name?

optional name: string

Defined in: form/reatomForm.ts:179

Inherited from

BaseFormOptions.name

onSubmit()?

optional onSubmit: (state, …params) => SubmitReturn | Promise<SubmitReturn>

Defined in: form/reatomForm.ts:255

The callback to process valid form data, typed according to the raw form state

Parameters

state

Deatomize<FormFields<T>>

params

…SubmitParams

Returns

SubmitReturn | Promise<SubmitReturn>

resetOnSubmit?

optional resetOnSubmit: boolean

Defined in: form/reatomForm.ts:186

Should reset the state after success submit?

Default

false

Inherited from

BaseFormOptions.resetOnSubmit

schema?

optional schema: undefined

Defined in: form/reatomForm.ts:267

Schema is explicitly disallowed or undefined in this variant

validateBeforeSubmit()?

optional validateBeforeSubmit: (state) => any

Defined in: form/reatomForm.ts:264

The callback to validate form fields before submit, typed according to the raw form state

Parameters

state

Deatomize<FormFields<T>>

Returns

any

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomForm.ts:219

Defines if the validation should be triggered on the field blur by default for all fields.

Default

false

Inherited from

BaseFormOptions.validateOnBlur

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomForm.ts:211

Defines if the validation should be triggered with every field change by default for all fields.

Default

false

Inherited from

BaseFormOptions.validateOnChange

FormOptionsWithSchema

Defined in: form/reatomForm.ts:222

Extends

BaseFormOptions

Type Parameters

State

State

SubmitReturn

SubmitReturn

SubmitParams

SubmitParams extends any[]

Properties

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomForm.ts:194

Defines the default reset behavior of the validation state during async validation for all fields.

Default

false

Inherited from

BaseFormOptions.keepErrorDuringValidating

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomForm.ts:203

Defines the default reset behavior of the validation state on field change for all fields. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

Inherited from

BaseFormOptions.keepErrorOnChange

name?

optional name: string

Defined in: form/reatomForm.ts:179

Inherited from

BaseFormOptions.name

onSubmit()?

optional onSubmit: (state, …params) => SubmitReturn | Promise<SubmitReturn>

Defined in: form/reatomForm.ts:228

The callback to process valid form data, typed according to the schema

Parameters

state

State

params

…SubmitParams

Returns

SubmitReturn | Promise<SubmitReturn>

resetOnSubmit?

optional resetOnSubmit: boolean

Defined in: form/reatomForm.ts:186

Should reset the state after success submit?

Default

false

Inherited from

BaseFormOptions.resetOnSubmit

schema

schema: StandardSchemaV1<unknown, State>

Defined in: form/reatomForm.ts:243

The schema which supports StandardSchemaV1 specification to validate form fields.

validateBeforeSubmit()?

optional validateBeforeSubmit: (state) => any

Defined in: form/reatomForm.ts:237

The callback to validate form fields before submit, typed according to the schema

Parameters

state

State

Returns

any

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomForm.ts:219

Defines if the validation should be triggered on the field blur by default for all fields.

Default

false

Inherited from

BaseFormOptions.validateOnBlur

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomForm.ts:211

Defines if the validation should be triggered with every field change by default for all fields.

Default

false

Inherited from

BaseFormOptions.validateOnChange

TransformableFieldOptions

Defined in: form/reatomField.ts:273

Extends

Omit<FieldOptions<State, Value>, "fromState" | "toState">

Type Parameters

State

State

Value

Value

Properties

disabled?

optional disabled: boolean

Defined in: form/reatomField.ts:238

Defines if the field is disabled by default.

Default

false

Inherited from

FormFieldOptions.disabled

elementRef?

optional elementRef: FieldElementRef

Defined in: form/reatomField.ts:241

Defines a default element reference accosiated with the field.

Inherited from

FormFieldOptions.elementRef

filter()?

optional filter: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:194

The callback to filter “value” changes (from the ‘change’ action). It should return ‘false’ to skip the update. By default, it always returns true.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

Inherited from

Omit.filter

fromState()

fromState: (state, self) => Value

Defined in: form/reatomField.ts:281

The callback to compute the “value” data from the “state” data. By default, it returns the “state” data without any transformations.

Parameters

state

State

self

FieldAtom<State, Value>

Returns

Value

isDirty()?

optional isDirty: (newValue, prevValue) => boolean

Defined in: form/reatomField.ts:225

The callback used to determine whether the “value” has changed. By default, it utilizes isDeepEqual from reatom/utils.

Parameters

newValue

Value

prevValue

Value

Returns

boolean

Inherited from

Omit.isDirty

keepErrorDuringValidating?

optional keepErrorDuringValidating: boolean

Defined in: form/reatomField.ts:248

Defines the reset behavior of the validation state during async validation.

Default

false

Inherited from

FormFieldOptions.keepErrorDuringValidating

keepErrorOnChange?

optional keepErrorOnChange: boolean

Defined in: form/reatomField.ts:256

Defines the reset behavior of the validation state on field change. Useful if the validation is triggered on blur or submit only.

Default

!validateOnChange

Inherited from

FormFieldOptions.keepErrorOnChange

name?

optional name: string

Defined in: form/reatomField.ts:228

The name of the field and all related atoms and actions.

Inherited from

FormFieldOptions.name

toState()

toState: (value, self) => State

Defined in: form/reatomField.ts:288

The callback to transform the “state” data from the “value” data from the change action. By default, it returns the “value” data without any transformations.

Parameters

value

Value

self

FieldAtom<State, Value>

Returns

State

validate?

optional validate: FieldValidateOption<State, Value> | StandardSchemaV1<State, State>

Defined in: form/reatomField.ts:231

The callback to validate the field.

Inherited from

Omit.validate

validateOnBlur?

optional validateOnBlur: boolean

Defined in: form/reatomField.ts:270

Defines if the validation should be triggered on the field blur.

Default

false

Inherited from

FormFieldOptions.validateOnBlur

validateOnChange?

optional validateOnChange: boolean

Defined in: form/reatomField.ts:263

Defines if the validation should be triggered with every field change.

Default

false

Inherited from

FormFieldOptions.validateOnChange

ValidationAtom()

Defined in: form/reatomField.ts:85

Base atom interface for other userspace implementations. This is the core interface that all atom-like objects implement, providing the foundation for Reatom’s reactivity system.

Extends

AtomLike<FieldValidation>

ValidationAtom(…params): FieldValidation

Defined in: form/reatomField.ts:85

Call the atom to either read or update its state.

Parameters

params

…any[]

Parameters to pass to the atom

Returns

FieldValidation

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

AtomLike.__reatom

clearErrors

clearErrors: Action<FieldErrorSource[], FieldValidation>

Defined in: form/reatomField.ts:93

Action to clear all errors by passed sources.

errors

errors: ArrayAtom<FieldError<any>>

Defined in: form/reatomField.ts:90

Full list of all errors related to the field

extend

extend: Extend<ValidationAtom>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

AtomLike.extend

set

set: unknown

Defined in: core/atom.ts:72

Inherited from

AtomLike.set

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

AtomLike.subscribe

trigger

trigger: Action<[], FieldValidation> & AbortExt

Defined in: form/reatomField.ts:87

Action to trigger field validation.

ValidationlessFieldSet()

Defined in: form/reatomFieldSet.ts:40

Derived state container.

A computed atom automatically tracks dependencies and recalculates only when those dependencies change. The calculation is performed lazily, only when the computed value is read AND subscribed to.

Extends

Computed<FormState<T>>

Type Parameters

T

T extends FormInitState

The type of derived state

ValidationlessFieldSet(…params): Deatomize

Defined in: form/reatomFieldSet.ts:40

Call the atom to either read or update its state.

Parameters

params

…[]

Parameters to pass to the atom

Returns

Deatomize

The atom’s payload (typically its current state)

Properties

__reatom

__reatom: AtomMeta

Defined in: core/atom.ts:92

Reference to the atom’s internal metadata.

Inherited from

Computed.__reatom

extend

extend: Extend<ValidationlessFieldSet<T>>

Defined in: core/atom.ts:78

Extension system to add capabilities to atoms. Allows adding middleware, methods, or other functionality to modify atom behavior.

Inherited from

Computed.extend

fieldArraysList

fieldArraysList: Computed<FormFieldArrayAtom[]>

Defined in: form/reatomFieldSet.ts:50

Computed list of all the field arrays from the fields tree

fields

fields: FormFields<T>

Defined in: form/reatomFieldSet.ts:44

Fields from the init state

fieldsList

fieldsList: Computed<FieldAtom<any, any>[]>

Defined in: form/reatomFieldSet.ts:47

Computed list of all the fields from the fields tree

focus

focus: Computed<FieldFocus>

Defined in: form/reatomFieldSet.ts:56

Atom with focus state of the fieldset, computed from all the fields in fieldsList

init

init: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:59

Action to set initial values for each field or field array in the fieldset

reset

reset: Action<[DeepPartial<Deatomize<FormFields<T>>, unknown[]>], void>

Defined in: form/reatomFieldSet.ts:62

Action to reset the state, the value, the validation, and the focus states.

set

set: unknown

Defined in: core/atom.ts:72

Inherited from

Computed.set

subscribe: (cb?) => Unsubscribe

Defined in: core/atom.ts:89

Parameters

cb?

(state) => any

Callback function that receives the atom’s state when it changes

Returns

Unsubscribe

An unsubscribe function that removes the subscription when called

Inherited from

Computed.subscribe

Type Aliases

ArrayFieldItem

ArrayFieldItem<T> = T extends LinkedListLikeAtom<infer _Node> ? AtomState<T["array"]>[number] : never

Defined in: form/reatomForm.ts:407

Type Parameters

T

T

DeepPartial

DeepPartial<T, Skip> = { [K in keyof T]?: T[K] extends Skip ? T[K] : T[K] extends Rec ? DeepPartial<T[K], Skip> : T[K] }

Defined in: form/reatomForm.ts:119

Type Parameters

T

T

Skip

Skip = never

FieldErrorSource

FieldErrorSource = "validation" | string & object

Defined in: form/reatomField.ts:56

FieldValidateOption()

FieldValidateOption<State, Value> = (meta) => FieldValidateOptionResult<State> | Promise<FieldValidateOptionResult<State>>

Defined in: form/reatomField.ts:170

Type Parameters

State

State = any

Value

Value = State

Parameters

Returns

FieldValidateOptionResult<State> | Promise<FieldValidateOptionResult<State>>

FieldValidateOptionResult

FieldValidateOptionResult<State> = string | string[] | FieldErrorBody | FieldErrorBody[] | StandardSchemaV1<State> | void | undefined

Defined in: form/reatomField.ts:179

Type Parameters

State

State = any

FormFieldArrayAtom

FormFieldArrayAtom<Param, Node> = LinkedListAtom<[ExtractFieldArray<Param>], FormFieldElement<Node>> & object

Defined in: form/reatomForm.ts:79

Type Declaration

initState

initState: Atom<LinkedList<LLNode<FormFieldElement<Node>>>>

reset

reset: Action<[], AtomState<FormFieldArrayAtom<Param, Node>>>

Type Parameters

Param

Param = any

Node

Node extends FormInitStateElement = FormInitStateElement

FormFieldElement

FormFieldElement<T> = T extends FieldLikeAtom ? T : T extends Date ? FieldAtom<T> : T extends boolean ? FieldAtom<boolean> : T extends infer Item[] ? Item extends FormInitStateElement ? FormFieldArrayAtom<Item, Item> : never : T extends FormFieldArray<infer Param, infer Node> ? FormFieldArrayAtom<Param, Node> : T extends FieldOptions & object ? T extends FieldOptions<State, State> ? FieldAtom<State> : T extends FieldOptions<State, infer Value> ? FieldAtom<State, Value> : object extends T ? FieldAtom<State, State> : never : T extends Rec<unknown> ? { [K in keyof T]: FormFieldElement<T[K]> } : FieldAtom<T>

Defined in: form/reatomForm.ts:87

Type Parameters

T

T extends FormInitStateElement | unknown = FormInitStateElement

FormFields

FormFields<T> = { [K in keyof T]: FormFieldElement<T[K]> }

Defined in: form/reatomForm.ts:113

Type Parameters

T

T extends FormInitState

FormInitState

FormInitState = object

Defined in: form/reatomForm.ts:69

Index Signature

[key: string]: FormInitStateElement | FormInitState

FormPartialState

FormPartialState<T> = DeepPartial<FormState<T>, unknown[]>

Defined in: form/reatomForm.ts:126

Type Parameters

T

T extends FormInitState

FormState

FormState<T> = Deatomize<FormFields<T>>

Defined in: form/reatomForm.ts:117

Type Parameters

T

T extends FormInitState

SubmitAction

SubmitAction<Params, Return> = Action<Params, Promise<Return>> & AsyncDataExt<Params, Return, Return | undefined, Error | undefined>

Defined in: form/reatomForm.ts:131

Type Parameters

Params

Params extends any[]

Return

Return

Variables

fieldInitFocus

const fieldInitFocus: FieldFocus

Defined in: form/reatomField.ts:291

fieldInitValidation

const fieldInitValidation: FieldValidation

Defined in: form/reatomField.ts:297

fieldInitValidationLess

const fieldInitValidationLess: FieldValidation

Defined in: form/reatomField.ts:303

Functions

experimental_fieldArray()

Call Signature

experimental_fieldArray<Param>(initState): FormFieldArray<Param, Param>

Defined in: form/reatomForm.ts:357

Type Parameters

Param

Param extends FormInitStateElement

Parameters

initState

Param[]

Returns

FormFieldArray<Param, Param>

Call Signature

experimental_fieldArray<Param, Node>(create): FormFieldArray<Param, Node>

Defined in: form/reatomForm.ts:361

Type Parameters

Param

Param

Node

Node extends FormInitStateElement = FormInitStateElement

Parameters

create

(params, name) => Node

Returns

FormFieldArray<Param, Node>

Call Signature

experimental_fieldArray<Param, Node>(options): FormFieldArray<Param, Node>

Defined in: form/reatomForm.ts:366

Type Parameters

Param

Param

Node

Node extends FormInitStateElement = FormInitStateElement

Parameters

options

create

(param, name) => Node

initState?

Param[]

Returns

FormFieldArray<Param, Node>

isFieldAtom()

isFieldAtom(thing): thing is FieldLikeAtom<any>

Defined in: form/reatomField.ts:693

Parameters

thing

any

Returns

thing is FieldLikeAtom<any>

reatomField()

Call Signature

reatomField<State>(_initState, options?): FieldAtom<State, State>

Defined in: form/reatomField.ts:309

Type Parameters

State

State

Parameters

_initState

State

options?

string | FieldOptions<State, State>

Returns

FieldAtom<State, State>

Call Signature

reatomField<State, Value>(_initState, options): FieldAtom<State, Value>

Defined in: form/reatomField.ts:314

Type Parameters

State

State

Value

Value

Parameters

_initState

State

options

TransformableFieldOptions<State, Value>

Returns

FieldAtom<State, Value>

Call Signature

reatomField<State, A, Value>(_initState, options, stateAtom): A & FieldAtom<State, Value>

Defined in: form/reatomField.ts:319

Type Parameters

State

State

A

A extends Atom<State, [State]>

Value

Value = State

Parameters

_initState

State

options

string | FieldOptions<State, Value>

stateAtom

A

Returns

A & FieldAtom<State, Value>

reatomFieldSet()

reatomFieldSet<T>(fields, name): FieldSet<T>

Defined in: form/reatomFieldSet.ts:78

Type Parameters

T

T extends FormInitState

Parameters

fields

FormFields<T>

name

string = ...

Returns

FieldSet<T>

reatomForm()

Call Signature

reatomForm<T, SchemaState, SubmitReturn, SubmitParams>(initState, optionsWithSchema): Form<T, SchemaState, SubmitReturn, SubmitParams>

Defined in: form/reatomForm.ts:440

Type Parameters

T

T extends FormInitState

SchemaState

SchemaState

SubmitReturn

SubmitReturn

SubmitParams

SubmitParams extends any[]

Parameters

initState

T | (name) => T

optionsWithSchema

FormOptionsWithSchema<SchemaState, SubmitReturn, SubmitParams>

Returns

Form<T, SchemaState, SubmitReturn, SubmitParams>

Call Signature

reatomForm<T, SubmitReturn, SubmitParams>(initState, options?): Form<T, undefined, SubmitReturn, SubmitParams>

Defined in: form/reatomForm.ts:454

Type Parameters

T

T extends FormInitState

SubmitReturn

SubmitReturn

SubmitParams

SubmitParams extends any[]

Parameters

initState

T | (name) => T

options?

FormOptionsWithoutSchema<T, SubmitReturn, SubmitParams>

Returns

Form<T, undefined, SubmitReturn, SubmitParams>

Call Signature

reatomForm<T>(initState, name?): Form<T, undefined, void, []>

Defined in: form/reatomForm.ts:463

Type Parameters

T

T extends FormInitState

Parameters

initState

T | (name) => T

name?

string

Returns

Form<T, undefined, void, []>

withField()

Call Signature

withField<T>(options?): (anAtom) => T & FieldAtom<AtomState<T>, AtomState<T>>

Defined in: form/reatomField.ts:678

Type Parameters

T

T extends Atom<any, [any]>

Parameters

options?

Omit<FieldOptions<AtomState<T>, AtomState<T>>, "name">

Returns

(anAtom): T & FieldAtom<AtomState<T>, AtomState<T>>

Parameters

anAtom

T

Returns

T & FieldAtom<AtomState<T>, AtomState<T>>

Call Signature

withField<T, Value>(options?): (anAtom) => T & FieldAtom<AtomState<T>, Value>

Defined in: form/reatomField.ts:682

Type Parameters

T

T extends Atom<any, [any]>

Value

Value

Parameters

options?

Omit<TransformableFieldOptions<AtomState<T>, Value>, "name">

Returns

(anAtom): T & FieldAtom<AtomState<T>, Value>

Parameters

anAtom

T

Returns

T & FieldAtom<AtomState<T>, Value>

Package @reatom/form

@reatom/form

Interfaces

BaseFormOptions

Extended by

Properties

keepErrorDuringValidating?

Default

keepErrorOnChange?

Default

name?

resetOnSubmit?

Default

validateOnBlur?

Default

validateOnChange?

Default

FieldAtom()

Extends

Type Parameters

State

Value

Parameters

params

Returns

Properties

__reatom

Inherited from

__reatomField

Inherited from

change

disabled

elementRef

extend

Inherited from

focus

initState

options

reset

subscribe()

Parameters

cb?

Returns

Inherited from

validation

value

Methods

set()

Call Signature

Parameters

update

Returns

Inherited from

Call Signature

Parameters

params

Returns

Inherited from

FieldElementRef

Properties

focus()

Parameters

options?

preventScroll?

Returns

FieldError

Extends

Extended by

Type Parameters

Meta

Properties

message

Inherited from

meta?

Inherited from

source

FieldErrorBody

Extended by

Type Parameters

Meta