mobx-sentinel API doc
    Preparing search index...

    Class Form<T>

    Form manages submission, fields, and bindings.

    Key features:

    • Manages form fields and their states
    • Supports nested forms
    • Manages form submission lifecycle
    • Provides binding system for UI integration
    • Integrates with Watcher for change detection
    • Integrates with Validator for validation

    Type Parameters

    • T

    Indexable

    • [k: `bind${Capitalize<string>}`]: unknown

      Extension fields for bindings

    Index

    Properties

    addHandler bind configure id validator watcher

    Accessors

    canSubmit config firstErrorMessage invalidFieldCount invalidFieldPathCount isBusy isDirty isSubmitting isValid isValidating subForms

    Methods

    dispose get getSafe getAllErrors getErrors getField markAsDirty reportError reset submit

    Properties

    addHandler: {
        (
            event: "willSubmit",
            handler: (abortSignal: AbortSignal) => Promise<boolean>,
        ): () => void;
        (
            event: "submit",
            handler: (abortSignal: AbortSignal) => Promise<boolean>,
        ): () => void;
        (event: "didSubmit", handler: (succeed: boolean) => void): () => void;
    } = ...

    Add a submission handler

    Handlers are called in this order:

    1. willSubmit - Called before submission starts
    2. submit - Async handlers that perform the submission (serialized)
    3. didSubmit - Called after submission completes

    Form.Handlers

    Function to remove the handler

    bind: FormBindingFunc<T> = ...

    Create UI binding for form elements

    • Can bind to individual fields
    • Can bind to multiple fields
    • Can bind to the entire form
    • Bindings are cached and reused
    • Supports configuration via binding classes
    configure: {
        (config: Partial<Readonly<FormConfig>>): void;
        (reset: true): void;
    } = ...

    Configure the form locally

    Type declaration

      • (config: Partial<Readonly<FormConfig>>): void

      • Override the global configuration locally

        Parameters

        Returns void

      • (reset: true): void

      • Reset to the global configuration

        Parameters

        • reset: true

        Returns void

    id: string = ...
    validator: Validator<T>
    watcher: Watcher

    Accessors

    • get canSubmit(): boolean

      Whether the form can be submitted

      Returns boolean

      • Checks if the form is not busy
      • Checks if the form is valid or allows invalid submissions
      • Checks if the form is dirty or allows non-dirty submissions
    • get config(): Readonly<FormConfig>

      The configuration of the form

      This is a computed value that combines the global configuration and the local configuration.

      Returns Readonly<FormConfig>

    • get firstErrorMessage(): null | string

      The first error message (including nested objects)

      Returns null | string

      Alias for Validator.firstErrorMessage.

    • get invalidFieldCount(): number

      The number of invalid fields

      Returns number

      Alias for Validator.invalidKeyCount.

    • get invalidFieldPathCount(): number

      The number of total invalid field paths (counts invalid fields in sub-forms)

      Returns number

      Alias for Validator.invalidKeyPathCount.

    • get isBusy(): boolean

      Whether the form is busy (submitting or validating)

      Returns boolean

    • get isDirty(): boolean

      Whether the form is dirty (including sub-forms)

      Returns boolean

      Alias for Watcher.changed.

    • get isSubmitting(): boolean

      Whether the form is in submitting state

      Returns boolean

    • get isValid(): boolean

      Whether the form is valid (including sub-forms)

      Returns boolean

      Alias for Validator.isValid.

    • get isValidating(): boolean

      Whether the form is in validator state

      Returns boolean

      Alias for Validator.isValidating.

    • get subForms(): ReadonlyMap<KeyPath, Form<any>>

      Sub-forms within the form.

      Forms are collected via @nested annotation.

      Returns ReadonlyMap<KeyPath, Form<any>>

    Methods

    • Manually dispose the form instance for the subject.

      Use with caution.
      You don't usually need to use this method at all.
      It's only for advanced use cases, such as testing.

      Parameters

      • subject: object
      • OptionalformKey: symbol

      Returns void

      Form.get

    • Get a form instance for the subject.

      Type Parameters

      • T extends object

      Parameters

      • subject: T

        The model object to create form for

      • OptionalformKey: symbol

        Optional key for multiple forms per subject

      Returns Form<T>

      • Returns existing instance if one exists for the subject
      • Creates new instance if none exists
      • Instances are cached and garbage collected with their subjects
      • Multiple forms per subject supported via formKey

      TypeError if subject is not an object

    • Get a form instance for the subject.

      Same as Form.get but returns null instead of throwing an error.

      Type Parameters

      • T extends object

      Parameters

      • subject: T
      • OptionalformKey: symbol

      Returns null | Form<T>

    • Get all error messages for the form

      Parameters

      • OptionalfieldName: Name<T>

        Field to get errors for. If omitted, all errors are returned.

      Returns Set<string>

      Set of error messages

    • Get error messages for a field

      Parameters

      • fieldName: Name<T>

        Field to get errors for

      • includePreReported: boolean = false

        Whether to include errors not yet reported

      Returns ReadonlySet<string>

      Set of error messages

    • Mark the form as dirty

      Returns void

      Alias for Watcher.assumeChanged.

    • Report error states on all fields and sub-forms

      Returns void

    • Reset the form's state

      Returns void

      • Resets the fields
      • Resets the sub-forms
      • Resets the watcher
      • Does not reset the validator

    • Submit the form.

      Parameters

      • Optionalargs: { force?: boolean }
        • Optionalforce?: boolean

          Whether to force submission even if canSubmit is false. It cancels any in-progress submission if any.

      Returns Promise<boolean>

      true if submission succeeded, false if failed or aborted

      • Checks if canSubmit is true
      • Executes handlers in order
      • Aborts if any submit handler returns false
      • Handles exceptions in all phases
      • Resets the form after successful submission

    Settings

    Member Visibility

    On This Page

    Properties
    Accessors
    Methods