@angular/forms/signals

submit

function

stablesince v22.0

Submits a given FieldTree using the given action function and applies any submission errors resulting from the action to the field. Submission errors returned by the action will be integrated into the field as a ValidationError on the sub-field indicated by the fieldTree property of the submission error.

API

function submit<TModel>(
  form: FieldTree<TModel>,
  options?: NoInfer<FormSubmitOptions<unknown, TModel>> | undefined,
): Promise<boolean>;
function submit<TModel>(
  form: FieldTree<TModel>,
  action: NoInfer<
    (
      field: FieldTree<TModel, string | number, 'writable'>,
      detail: {
        root: FieldTree<unknown, string | number, 'writable'>;
        submitted: FieldTree<TModel, string | number, 'writable'>;
      },
    ) => Promise<TreeValidationResult<WithOptionalFieldTree>>
  >,
): Promise<boolean>;

function submit<TModel>(form: FieldTree<TModel>, options?: NoInfer<FormSubmitOptions<unknown, TModel>> | undefined): Promise<boolean>;

Concurrent submissions are prohibited. If a submit is already in progress for the given field or any of its parents, subsequent calls to submit will return false immediately without running the action.

@paramformFieldTree<TModel>

The field to submit.

@paramoptionsNoInfer<FormSubmitOptions<unknown, TModel>> | undefined

Options for the submission.

@returnsPromise<boolean>

Whether the submission was successful.

Usage notes

async function registerNewUser(registrationForm: FieldTree<{username: string, password: string}>) {
  const result = await myClient.registerNewUser(registrationForm().value());
  if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
    return [{
      fieldTree: registrationForm.username,
      kind: 'server',
      message: 'Username already taken'
    }];
  }
  return undefined;
}

const registrationForm = form(signal({username: 'god', password: ''}));
submit(registrationForm, {
  action: async (f) => {
    return registerNewUser(registrationForm);
  }
});
registrationForm.username().errors(); // [{kind: 'server', message: 'Username already taken'}]

function submit<TModel>(form: FieldTree<TModel>, action: NoInfer<(field: FieldTree<TModel, string | number, "writable">, detail: { root: FieldTree<unknown, string | number, "writable">; submitted: FieldTree<TModel, string | number, "writable">; }) => Promise<TreeValidationResult<WithOptionalFieldTree>>>): Promise<boolean>;

@paramformFieldTree<TModel>

@paramaction

NoInfer<(field: FieldTree<TModel, string | number, "writable">, detail: { root: FieldTree<unknown, string | number, "writable">; submitted: FieldTree<TModel, string | number, "writable">; }) => Promise<TreeValidationResult<WithOptionalFieldTree>>>

@returnsPromise<boolean>

Description

Usage Notes

async function registerNewUser(registrationForm: FieldTree<{username: string, password: string}>) {
  const result = await myClient.registerNewUser(registrationForm().value());
  if (result.errorCode === myClient.ErrorCode.USERNAME_TAKEN) {
    return [{
      fieldTree: registrationForm.username,
      kind: 'server',
      message: 'Username already taken'
    }];
  }
  return undefined;
}

const registrationForm = form(signal({username: 'god', password: ''}));
submit(registrationForm, {
  action: async (f) => {
    return registerNewUser(registrationForm);
  }
});
registrationForm.username().errors(); // [{kind: 'server', message: 'Username already taken'}]