Learning Objectives

Understanding Server Actions
Form handling with React 19
Form validation
Error handling and feedback
Optimistic updates

1. What are Server Actions?

Server Actions are async functions that run on the server. They provide a secure way to handle form submissions and data mutations without creating separate API endpoints. The "use server" directive marks a function as a Server Action.

Server Actions can be called from Client or Server Components, making them versatile for handling user input across your application.

// Server Action definition
async function createTransaction(formData: FormData) {
  "use server";

  const type = formData.get("type");
  const amount = formData.get("amount");

  // This runs on the server
  await db.transaction.create({
    data: { type, amount: Number(amount) },
  });
}

Benefits

Server Actions simplify full-stack development by eliminating the need for separate API endpoints for form submissions. Here are the key advantages they provide.

No API routes needed for simple mutations
Automatic form handling
Progressive enhancement (works without JS)
Type-safe with TypeScript
Integrated with React 19 features

2. Basic Form with Server Action

The simplest way to use Server Actions is by defining them inline within a Server Component. The action prop connects the form directly to the server function.

In a Server Component

This example shows a complete airtime purchase form. The Server Action receives FormData, processes the purchase, revalidates cached data, and redirects the user to see their transaction.

// app/services/airtime/page.tsx
export default function AirtimePage() {
  async function buyAirtime(formData: FormData) {
    "use server";

    const phone = formData.get("phone") as string;
    const amount = formData.get("amount") as string;
    const network = formData.get("network") as string;

    // Process the purchase
    await processAirtimePurchase({ phone, amount: Number(amount), network });

    // Revalidate and redirect
    revalidatePath("/transactions");
    redirect("/transactions");
  }

  return (
    <form action={buyAirtime} className="space-y-4">
      <div>
        <label htmlFor="network">Network</label>
        <select name="network" id="network" required>
          <option value="mtn">MTN</option>
          <option value="airtel">Airtel</option>
          <option value="glo">Glo</option>
          <option value="9mobile">9Mobile</option>
        </select>
      </div>

      <div>
        <label htmlFor="phone">Phone Number</label>
        <input
          type="tel"
          name="phone"
          id="phone"
          placeholder="08012345678"
          required
        />
      </div>

      <div>
        <label htmlFor="amount">Amount</label>
        <input
          type="number"
          name="amount"
          id="amount"
          min="50"
          max="50000"
          required
        />
      </div>

      <button
        type="submit"
        className="w-full bg-primary text-white py-3 rounded"
      >
        Buy Airtime
      </button>
    </form>
  );
}

3. Server Actions in Separate File

For better organization and reusability, define Server Actions in dedicated files. Adding "use server" at the top of the file marks all exported functions as Server Actions.

Separating actions into their own files makes them reusable across multiple components and easier to test. The Zod schema provides runtime validation for the incoming form data.

// actions/transactions.ts
"use server";

import { revalidatePath } from "next/cache";
import { redirect } from "next/navigation";
import { z } from "zod";

// Validation schema
const AirtimeSchema = z.object({
  network: z.enum(["mtn", "airtel", "glo", "9mobile"]),
  phone: z.string().min(11).max(11),
  amount: z.number().min(50).max(50000),
});

export async function buyAirtime(formData: FormData) {
  // Parse and validate
  const rawData = {
    network: formData.get("network"),
    phone: formData.get("phone"),
    amount: Number(formData.get("amount")),
  };

  const validatedData = AirtimeSchema.parse(rawData);

  // Process purchase
  await db.transaction.create({
    data: {
      type: "airtime",
      ...validatedData,
      status: "pending",
    },
  });

  revalidatePath("/transactions");
  redirect("/transactions");
}

Using in Component

Import the action and pass it directly to the form's action prop. The component remains clean and focused on presentation while the action handles all the business logic.

// app/services/airtime/page.tsx
import { buyAirtime } from "@/actions/transactions";

export default function AirtimePage() {
  return <form action={buyAirtime}>{/* form fields */}</form>;
}

4. useActionState Hook (React 19)

The useActionState hook manages form state including submission status, validation errors, and success messages. It wraps your Server Action and provides a stateful form experience.

Server Action with Form State

The Server Action must accept the previous state as its first parameter and return a state object. This pattern enables displaying validation errors and success messages to the user.

// actions/auth.ts
"use server";

import { z } from "zod";

const LoginSchema = z.object({
  email: z.string().email("Invalid email"),
  password: z.string().min(8, "Password must be at least 8 characters"),
});

export interface FormState {
  success: boolean;
  message: string;
  errors?: {
    email?: string[];
    password?: string[];
  };
}

export async function login(
  prevState: FormState,
  formData: FormData
): Promise<FormState> {
  const rawData = {
    email: formData.get("email"),
    password: formData.get("password"),
  };

  // Validate
  const result = LoginSchema.safeParse(rawData);

  if (!result.success) {
    return {
      success: false,
      message: "Validation failed",
      errors: result.error.flatten().fieldErrors,
    };
  }

  // Attempt login
  try {
    await signIn(result.data.email, result.data.password);
    return { success: true, message: "Login successful" };
  } catch (error) {
    return {
      success: false,
      message: "Invalid credentials",
    };
  }
}

Client Component Form

The useActionState hook returns the current state, a wrapped action function, and a pending boolean. Use these to display feedback and disable the form during submission.

// components/LoginForm.tsx
"use client";

import { useActionState } from "react";
import { login, type FormState } from "@/actions/auth";

const initialState: FormState = {
  success: false,
  message: "",
};

export default function LoginForm() {
  const [state, formAction, isPending] = useActionState(login, initialState);

  return (
    <form action={formAction} className="space-y-4">
      {state.message && (
        <div
          className={`p-4 rounded ${
            state.success
              ? "bg-green-100 text-green-700"
              : "bg-red-100 text-red-700"
          }`}
        >
          {state.message}
        </div>
      )}

      <div>
        <label htmlFor="email">Email</label>
        <input
          type="email"
          name="email"
          id="email"
          className={state.errors?.email ? "border-red-500" : ""}
        />
        {state.errors?.email && (
          <p className="text-red-500 text-sm">{state.errors.email[0]}</p>
        )}
      </div>

      <div>
        <label htmlFor="password">Password</label>
        <input
          type="password"
          name="password"
          id="password"
          className={state.errors?.password ? "border-red-500" : ""}
        />
        {state.errors?.password && (
          <p className="text-red-500 text-sm">{state.errors.password[0]}</p>
        )}
      </div>

      <button
        type="submit"
        disabled={isPending}
        className="w-full bg-primary text-white py-3 rounded disabled:opacity-50"
      >
        {isPending ? "Logging in..." : "Login"}
      </button>
    </form>
  );
}

5. useFormStatus Hook

The useFormStatus hook provides the pending state of the parent form. Create a separate component to access this state, as it must be a child of the form element.

Reusable Submit Button

This submit button component automatically shows loading state when the form is submitting. It works with any form that uses a Server Action.

// components/SubmitButton.tsx
"use client";

import { useFormStatus } from "react-dom";

interface SubmitButtonProps {
  children: React.ReactNode;
  loadingText?: string;
}

export default function SubmitButton({
  children,
  loadingText = "Processing...",
}: SubmitButtonProps) {
  const { pending } = useFormStatus();

  return (
    <button
      type="submit"
      disabled={pending}
      className="w-full bg-primary text-white py-3 rounded disabled:opacity-50"
    >
      {pending ? loadingText : children}
    </button>
  );
}

Usage

Simply replace your regular submit button with the SubmitButton component. It automatically detects when the form is submitting and shows the appropriate loading state.

// Usage
<form action={buyAirtime}>
  {/* fields */}
  <SubmitButton loadingText="Processing purchase...">Buy Airtime</SubmitButton>
</form>

6. Form Validation with Zod

Zod provides type-safe schema validation for your form data. Install it to add runtime validation that integrates seamlessly with TypeScript.

pnpm add zod

Validation Schemas

Define reusable schemas for common validation patterns like phone numbers. Complex schemas can compose simpler ones, and the refine method adds custom validation logic.

// lib/validations.ts
import { z } from "zod";

export const phoneNumberSchema = z
  .string()
  .regex(/^0[789][01]\d{8}$/, "Invalid Nigerian phone number");

export const airtimeSchema = z.object({
  network: z.enum(["mtn", "airtel", "glo", "9mobile"]),
  phone: phoneNumberSchema,
  amount: z
    .number()
    .min(50, "Minimum amount is ₦50")
    .max(50000, "Maximum amount is ₦50,000"),
});

export const dataSchema = z.object({
  network: z.enum(["mtn", "airtel", "glo", "9mobile"]),
  phone: phoneNumberSchema,
  planId: z.string().min(1, "Please select a data plan"),
});

export const electricitySchema = z.object({
  disco: z.string().min(1, "Please select a distribution company"),
  meterNumber: z.string().min(11).max(13),
  meterType: z.enum(["prepaid", "postpaid"]),
  amount: z.number().min(1000).max(500000),
});

export const registrationSchema = z
  .object({
    name: z.string().min(2, "Name must be at least 2 characters"),
    email: z.string().email("Invalid email address"),
    phone: phoneNumberSchema,
    password: z
      .string()
      .min(8, "Password must be at least 8 characters")
      .regex(/[A-Z]/, "Password must contain at least one uppercase letter")
      .regex(/[0-9]/, "Password must contain at least one number"),
    confirmPassword: z.string(),
  })
  .refine((data) => data.password === data.confirmPassword, {
    message: "Passwords don't match",
    path: ["confirmPassword"],
  });

7. Complete Purchase Form Example

This comprehensive example brings together all the concepts: Server Actions, Zod validation, useActionState, and proper error handling. It demonstrates a production-ready form implementation.

Server Action

The action validates input with Zod, checks business rules like wallet balance, processes the transaction, and returns appropriate success or error states.

// actions/airtime.ts
"use server";

import { revalidatePath } from "next/cache";
import { airtimeSchema } from "@/lib/validations";
import { processAirtime } from "@/lib/rizpay";

export interface AirtimeFormState {
  success: boolean;
  message: string;
  errors?: Record<string, string[]>;
  transaction?: {
    id: string;
    reference: string;
  };
}

export async function purchaseAirtime(
  prevState: AirtimeFormState,
  formData: FormData
): Promise<AirtimeFormState> {
  // Parse form data
  const rawData = {
    network: formData.get("network") as string,
    phone: formData.get("phone") as string,
    amount: Number(formData.get("amount")),
  };

  // Validate
  const result = airtimeSchema.safeParse(rawData);
  if (!result.success) {
    return {
      success: false,
      message: "Please fix the errors below",
      errors: result.error.flatten().fieldErrors,
    };
  }

  try {
    // Check wallet balance
    const wallet = await getWalletBalance();
    if (wallet.balance < result.data.amount) {
      return {
        success: false,
        message: "Insufficient wallet balance",
      };
    }

    // Process purchase
    const transaction = await processAirtime(result.data);

    // Revalidate cache
    revalidatePath("/transactions");
    revalidatePath("/wallet");

    return {
      success: true,
      message: "Airtime purchase successful!",
      transaction: {
        id: transaction.id,
        reference: transaction.reference,
      },
    };
  } catch (error) {
    return {
      success: false,
      message: error instanceof Error ? error.message : "Purchase failed",
    };
  }
}

Form Component

The form component uses controlled inputs for the interactive elements (network selection and quick amount buttons) while letting the form handle the actual values for submission.

// components/AirtimeForm.tsx
"use client";

import { useActionState, useState } from "react";
import { purchaseAirtime, type AirtimeFormState } from "@/actions/airtime";
import SubmitButton from "@/components/SubmitButton";

const networks = [
  { id: "mtn", name: "MTN", color: "bg-yellow-500" },
  { id: "airtel", name: "Airtel", color: "bg-red-500" },
  { id: "glo", name: "Glo", color: "bg-green-500" },
  { id: "9mobile", name: "9Mobile", color: "bg-green-700" },
];

const quickAmounts = [100, 200, 500, 1000, 2000, 5000];

const initialState: AirtimeFormState = {
  success: false,
  message: "",
};

export default function AirtimeForm() {
  const [state, formAction] = useActionState(purchaseAirtime, initialState);
  const [selectedNetwork, setSelectedNetwork] = useState("");
  const [amount, setAmount] = useState("");

  return (
    <form action={formAction} className="space-y-6">
      {/* Success/Error Message */}
      {state.message && (
        <div
          className={`p-4 rounded-lg ${
            state.success
              ? "bg-green-100 text-green-700"
              : "bg-red-100 text-red-700"
          }`}
        >
          {state.message}
          {state.transaction && (
            <p className="text-sm mt-1">
              Reference: {state.transaction.reference}
            </p>
          )}
        </div>
      )}

      {/* Network Selection */}
      <div>
        <label className="block text-sm font-medium mb-2">Select Network</label>
        <div className="grid grid-cols-4 gap-3">
          {networks.map((network) => (
            <label
              key={network.id}
              className={`
                flex flex-col items-center p-4 rounded-lg border-2 cursor-pointer
                ${
                  selectedNetwork === network.id
                    ? "border-primary bg-primary/10"
                    : "border-gray-200 hover:border-gray-300"
                }
              `}
            >
              <input
                type="radio"
                name="network"
                value={network.id}
                checked={selectedNetwork === network.id}
                onChange={(e) => setSelectedNetwork(e.target.value)}
                className="sr-only"
              />
              <div className={`w-10 h-10 rounded-full ${network.color}`} />
              <span className="mt-2 text-sm font-medium">{network.name}</span>
            </label>
          ))}
        </div>
        {state.errors?.network && (
          <p className="text-red-500 text-sm mt-1">{state.errors.network[0]}</p>
        )}
      </div>

      {/* Phone Number */}
      <div>
        <label htmlFor="phone" className="block text-sm font-medium mb-2">
          Phone Number
        </label>
        <input
          type="tel"
          name="phone"
          id="phone"
          placeholder="08012345678"
          className={`w-full p-3 border rounded-lg ${
            state.errors?.phone ? "border-red-500" : "border-gray-300"
          }`}
        />
        {state.errors?.phone && (
          <p className="text-red-500 text-sm mt-1">{state.errors.phone[0]}</p>
        )}
      </div>

      {/* Quick Amount Buttons */}
      <div>
        <label className="block text-sm font-medium mb-2">Amount</label>
        <div className="grid grid-cols-3 gap-2 mb-3">
          {quickAmounts.map((quickAmount) => (
            <button
              key={quickAmount}
              type="button"
              onClick={() => setAmount(quickAmount.toString())}
              className={`p-2 rounded border ${
                amount === quickAmount.toString()
                  ? "border-primary bg-primary/10"
                  : "border-gray-200 hover:border-gray-300"
              }`}
            >
              ₦{quickAmount.toLocaleString()}
            </button>
          ))}
        </div>
        <input
          type="number"
          name="amount"
          value={amount}
          onChange={(e) => setAmount(e.target.value)}
          placeholder="Or enter custom amount"
          min="50"
          max="50000"
          className={`w-full p-3 border rounded-lg ${
            state.errors?.amount ? "border-red-500" : "border-gray-300"
          }`}
        />
        {state.errors?.amount && (
          <p className="text-red-500 text-sm mt-1">{state.errors.amount[0]}</p>
        )}
      </div>

      <SubmitButton loadingText="Processing...">Buy Airtime</SubmitButton>
    </form>
  );
}

8. Optimistic Updates

Optimistic updates immediately show the expected result of an action before the server responds. This creates a snappy, responsive user experience. The useOptimistic hook manages this temporary state.

The hook takes the current state and an update function. When you call the setter, it immediately applies the optimistic update, then reconciles with the actual result when the server responds.

"use client";

import { useOptimistic, useActionState } from "react";
import { toggleFavorite } from "@/actions/favorites";

export default function FavoriteButton({ productId, isFavorite }: Props) {
  const [optimisticFavorite, setOptimisticFavorite] = useOptimistic(isFavorite);

  async function handleToggle() {
    setOptimisticFavorite(!optimisticFavorite);
    await toggleFavorite(productId);
  }

  return (
    <button onClick={handleToggle}>{optimisticFavorite ? "❤️" : "🤍"}</button>
  );
}

Additional Resources

Next Lesson: API Routes