useSubmission

This helper is used to handle form submissions and can provide optimistic updates while actions are in flight as well as pending state feedback. This method will return a single (latest) value while its sibling, useSubmissions, will return all values submitted while the component is active. With an optional second parameter for a filter function.

It's important to note that useSubmission requires the form method to be post otherwise it will trigger a browser navigation and will not work.

import { useSubmission } from "@solidjs/router";

function Component() {
  const submission = useSubmission(postNameAction);

    return (
      <form action={postNameAction} method="post">
          <input type="text" name="name" />
          <button type="submit">
              {submission.pending ? "Adding..." : "Add"}
          </button>
      </form>
    )
}

Creating the action

The Action which will trigger the submission should be created with the action() helper and, when in a SolidStart app, it is recommended to leverage the "use server" directive to leverage the caching and RPC capabilities from the server-side.

import { action } from "@solidjs/router";

const postNameAction = action(() => {
  "use server";
  /*... logic ...*/
  return { data: "Hello SolidStart" };
})

Filtering Submissions

As an optional second parameter, the useSubmission helper can receive a filter function to only return the submission that matches the condition. The filter receives the submitted dated as a parameter and should return a boolean value. E.g.: action below will only submit if the name is "solid".

import { useSubmission } from "@solidjs/router";

function Component() {
  const submission = useSubmission(postNameAction, ([formData]) => {
    const name = formData.get("name") ?? "";

    return name === "solid";
  });

    return (
      <form action={postNameAction} method="post">
          <input type="text" name="name" />
          <button type="submit">
              {submission.pending ? "Adding..." : "Add"}
          </button>
      </form>
    )
}

Optimistic Updates

When the form is submitted, the submission object will be updated with the new value and the pending property will be set to true. This allows you to provide feedback to the user that the action is in progress. Once the action is complete, the pending property will be set to false and the result property will be updated with final value.

Error Handling

If the action fails, the submission object will be updated with the error and the pending property will be set to false. This allows you to provide feedback to the user that the action has failed. Additionally, the return type of useSubmission will have a new key error that will contain the error object thrown by the submission handler.

At this stage, you can also use the retry() method to attempt the action again or the clear() to wipe the filled data in the platform.

import { Show } from "solid-js";
import { useSubmission } from "@solidjs/router";

function Component() {
  const submission = useSubmission(postNameAction);

    return (
      <>
        <Show when={submission.error}>
          {(error) => (
            <div>
              <p>Error: {error.message}</p>
              <button onClick={() => submission.clear()}>
                Clear
              </button>
              <button onClick={async () => submission.retry()}>
               Retry
              </button>
            </div>
          )}
        </Show>

        <form method="post" action={sendData}>
          <input type="text" name="name" required />
          <button type="submit" disabled={submission.pending}>
            {submission.pending ? "Submitting" : "Submit"}
          </button>
        </form>
      </>
    )
}