Skip to content
forms

Submit and starting values

Refuse a submit, act after one, and give the form its starting value.

Refusing a submit

A throw or a rejected promise in onSubmit is a bug. It goes to onPluginError and the submit carries on. To stop a submit on purpose, return refuse, directly or from the promise. The definition’s onSubmit isn’t called, the submission ends "invalid" as it does when validation fails, and onSubmitted gets it. Set a form error first so the user sees why:

import { definePlugin, refuse } from "@lunarhue/forms-core/plugins";

const captcha = definePlugin({
  name: "captcha",
  setup: (ctx) => ({
    async onSubmit() {
      try {
        const token = await fetchToken();
        ctx.write(() => ctx.store.root.at("token").setValue(token, { edited: false }));
        return undefined;
      } catch {
        ctx.store.root.setErrors({ message: "We couldn't check the form. Try again." });
        return refuse;
      }
    },
  }),
});

refuse returned directly stops the plugins after this one from running their onSubmit. Returned from a promise it can’t, since every onSubmit started when the submit did. A plugin doesn’t know the form’s error type, so the error it sets must fit the form’s mapError, if it has one.

After a submit

onSubmitted(submission, input) runs once a submit ends. input is the form value the definition’s onSubmit got as ctx.input, read when validation finished, so it holds edits the user made while validation ran. It is undefined when the submit ended "invalid". A submit that a reset stops never reaches onSubmitted.

To make a value the baseline, call ctx.baseline.move(path, value, keep). Each array in value pairs its items with the current items by index. keep changes that for one array, by its stable path: return true to keep the old baseline’s pairing, or a list of item keys to pair with. baselineOnSubmit passes the keys each array had when the value was sent.

Starting values

A plugin can give the form its starting value with initial. It runs before the store is made, gets the value the store would start from, and returns the value to start from instead, or undefined to keep it:

// Starts the form from a value the server and the client both have.
const startFrom = (value: Profile) => definePlugin({ name: "start", initial: () => value, setup: () => ({}) });

The store, its baseline and its server snapshot all start from that value. Nothing is written, so the form isn’t dirty and no plugin sees a record. When several plugins have initial, each gets the value the one before returned, so the last one in the list wins.

The value replaces the store’s starting value whole. It isn’t merged with a schema plugin’s defaults the way defaultValues is, though initial gets those merged defaults and can merge into them itself. A value that differs between server and client, such as one read from browser storage, makes hydration fail. Read those in onActive and write them with ctx.write, as persist does.

attach can return an initial hook too. It gets the value at the part’s path when the part attaches and returns the value to keep there, which is how mask cleans a field’s starting value. The store keeps it with no write record, and the baseline moves with it while the field isn’t dirty, so the form doesn’t start dirty.

Last updated