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
    addHandler bind configure id stableId validator watcher
    canSubmit config firstErrorMessage invalidFieldCount invalidFieldPathCount isBusy isDirty isSubmitting isValid isValidating subForms
    dispose get getSafe getAllErrors getErrors getField markAsDirty reportError reset submit
    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, to veto or prepare it (serialized; false stops the submission)
    2. submit - Async handlers that perform the submission and return whether it succeeded (serialized)
    3. didSubmit - Called once with the outcome after submission completes, except for a submission cancelled by a newer one

    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 = ...

    Identity of the form instance

    Unique per instance and fixed for its lifetime, but not reproducible: a server render and the client render that hydrates it produce different values. For an id that reaches the DOM, use stableId instead.

    stableId: string = ...

    Id of the form for the DOM, which the FormField.stableId of its fields build on

    Starts as id: unique on the page, but different between a server render and the client render that hydrates it. For a server-rendered form, assign an id that both arrive at. It is used as is, so nothing else on the page may use it. useId(), by way of useFormSSR from @mobx-sentinel/react, is both; a key from your own data works as long as it is unique on the page.

    Not reactive: bindings read it as they are called, so assign it before binding, and on every render if it can change. Assigning id back leaves the fields on their own ids again.

    Applies to this form alone. A sub-form is a separate instance with its own.

    validator: Validator<T>
    watcher: Watcher
    • 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(): string | null

      The first error message (including nested objects)

      Returns string | null

      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>>

    • 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 the subject only if everything they observe is too
      • 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 Form<T> | null

    • 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 the submission in progress, if any. The cancelled submission resolves false without calling didSubmit handlers.

      Returns Promise<boolean>

      true if submission succeeded, false if failed or cancelled

      • Checks if canSubmit is true, and returns false without running any handler if not
      • Executes handlers in order (see addHandler)
      • Fails if any willSubmit or submit handler returns false
      • Handles exceptions in all phases
      • Resets the form after successful submission

    Settings
    Member Visibility

    On This Page
    Properties
    Accessors
    Methods