Core Concept

Modern React extends the action prop of the native html form’s allowing you to easily invoke server functions without having to explicitly create HTTP Apis.

Server Functions invoked from a form.action prop are called Server Actions.

Native `form` `action`

Native browser form elements provide an action prop where you can pass in a URL which will be invoked with FormData upon form submission.

We could actually create a custom HTTP API with nextjs to handle the native "action -> HTTP API URL" functionality as shown below.

app/page.tsx

app/api/login/route.ts

"use client";

import { useState } from "react";

export default function Page() {
  const [name, setName] = useState("");
  return (
    <div className="root">
      <form action="/api/login" method="POST">
        <input
          name="username"
          value={name}
          onChange={(e) => setName(e.target.value)}
          placeholder="Enter your name"
        />
        <button type="submit">Submit</button>
      </form>
    </div>
  );
}

Extension to invoke Server Functions

Instead of passing in a url to the action prop, with modern React you can even directly pass in a server function which will automatically be invoked upon form submission with the FormData passed in as the argument.

This is demonstrated in the below example where our server function is directly invoked from the action prop with the FormData containing the fields in the form (username).

app/page.tsx

lib/functions.ts

"use client";

import { login } from "@/lib/functions";
import { useState } from "react";

export default function Page() {
  const [name, setName] = useState("");

  return (
    <div className="root">
      <form action={login}>
        <input
          name="username"
          value={name}
          onChange={(e) => setName(e.target.value)}
          placeholder="Enter your name"
        />
        <button type="submit">Submit</button>
      </form>
    </div>
  );
}

Create a Wrapper

Note that instead of passing in the server function directly to the action prop you can create a wrapper (e.g. with useTransition) which allows you provide better handling of the inputs and the outputs of the server function.

This is demonstrated in the below example where we invoke the server function with an object that has a well defined structure and then process the response to display it to the user.

app/page.tsx

lib/functions.ts

"use client";

import { useState, useTransition } from "react";
import { login, LoginResponse } from "@/lib/functions";

export default function Page() {
  const [name, setName] = useState("");
  const [isPending, startTransition] = useTransition();
  const [serverResult, setServerResult] = useState<LoginResponse | null>(null);

  function handleChange(e: React.ChangeEvent<HTMLInputElement>) {
    setName(e.target.value);
    setServerResult(null);
  }

  function handleSubmit() {
    startTransition(async () => {
      const result = await login({ username: name });
      setServerResult(result);
    });
  }

  return (
    <div className="root">
      <form action={handleSubmit}>
        <input
          name="username"
          value={name}
          onChange={handleChange}
          placeholder="Enter your username"
          disabled={isPending}
        />
        <button type="submit" disabled={isPending}>
          Submit
        </button>
      </form>

      {serverResult != null && (
        <p className={serverResult.type}>{serverResult.message}</p>
      )}
    </div>
  );
}

Transcript