Data APIs

useSubmissions

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 an iterable of all submitted actions while its component is mounted. With an optional second parameter for a filter function.

tip:

If you only care for the latest submission, you can use the useSubmission helper.

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

In the example below, the useSubmissions helper is used to retain a list of all submission results to that action while also giving feedback on the pending state of the current in-flight submission.

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

function Component() {
  const submissions = useSubmissions(postNameAction);

    return (
      <form method="post" action={postNameAction}>
        <ul>
          <For each={Array.from(submissions.entries())}>
            {([attemptIndex, data]) => (
                <Show when={data.result}>
                    { result => (
                        <li>
                            Backend {attemptIndex}: {result.name}
                        </li>
                    )}
                </Show>
              </>
            )}
          </For>
        </ul>
        <input name="name" type="text" />
        <button type="submit">{submissions.pending ? "sending" : "send"}</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. If in a SolidStart app 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 useSubmissions 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 { useSubmissions } from "@solidjs/router";

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

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

  return (
    <form method="post" action={postNameAction}>
        <ul>
            <For each={Array.from(submissions.entries())}>
                {([attemptIndex, data]) => (
                    <Show when={data.result}>
                        { result => (
                            <li>
                                Backend {attemptIndex}: {result.name}
                            </li>
                        )}
                    </Show>
                </>
                )}
            </For>
        </ul>
        <input name="name" type="text" />
        <button type="submit">{submissions.pending ? "sending" : "send"}</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 { useSubmissions } from "@solidjs/router";

function Component() {
  const submissions = useSubmissions(postNameAction);

    return (
      <form method="post" action={postNameAction}>
        <ul>
          <For each={Array.from(submissions.entries())}>
            {([attempt, data]) => (
              <Show when={data.error}>
                <li>
                  <p>Backend {attempt}: {data.error.message}</p>
                  <button onClick={() => data.retry()}>retry</button>
                  <button onClick={() => data.clear()}>clear</button>
                </li>
              </Show>
            )}
          </For>
        </ul>
        <input name="name" type="text" required autocomplete="off" />
        <button type="submit">{submissions.pending ? "sending" : "send"}</button>
      </form>
    )
}

Report an issue with this page