next-action-form

A TypeScript library for handling form actions in Next.js with server actions, useActionState, and Zod validation.

Installation

npm install next-action-form zod

Quick Start

1. Create your Zod schema

// validation/login.ts
import { z } from "zod";

export const loginSchema = z.object({
  email: z.string().email("Enter a valid email"),
  password: z.string().min(8, "Password must be at least 8 characters"),
});

2. Create your server action

// actions/login.ts
"use server";
import { createFormAction } from "next-action-form";
import { loginSchema } from "@/validation/login";

export const loginAction = createFormAction(loginSchema, async (data) => {
  // `data` is fully typed as { email: string; password: string }
  
  const response = await fetch("/api/login", {
    method: "POST",
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    return { success: false, message: "Invalid credentials" };
  }

  return { success: true, message: "Logged in successfully!" };
});

3. Use in your component

// components/LoginForm.tsx
"use client";
import { useForm } from "next-action-form/client";
import { loginAction } from "@/actions/login";

export function LoginForm() {
  const { formAction, isPending, state, getFieldError } = useForm(loginAction);

  return (
    <form action={formAction}>
      {state.message && (
        <div className={state.success ? "success" : "error"}>
          {state.message}
        </div>
      )}

      <input 
        name="email" 
        type="email"
        defaultValue={state.values?.email} 
      />
      {getFieldError("email") && <span>{getFieldError("email")}</span>}

      <input 
        name="password" 
        type="password" 
      />
      {getFieldError("password") && <span>{getFieldError("password")}</span>}

      <button type="submit" disabled={isPending}>
        {isPending ? "Signing in..." : "Sign In"}
      </button>
    </form>
  );
}

API Reference

createFormAction(schema, handler, options?)

Creates a server action with built-in Zod validation.

| Parameter | Type | Description | |-----------|------|-------------| | schema | ZodObject | The Zod schema to validate form data | | handler | (data) => Promise<FormState> | Handler receiving validated data | | options.validationErrorMessage | string | Custom validation error message |

useForm(action, initialState?)

A wrapper hook around useActionState with utilities.

Returns: | Property | Type | Description | |----------|------|-------------| | state | FormState | Current form state | | formAction | function | Action to pass to <form action={...}> | | isPending | boolean | Whether form is submitting | | isSuccess | boolean | Whether submission succeeded | | hasError | boolean | Whether there's an error | | getFieldError(field) | function | Get error for a field | | getFieldValue(field) | function | Get submitted value |

FormState<T>

type FormState<T> = {
  success: boolean;
  message?: string;
  fieldErrors?: Partial<Record<keyof T, string>>;
  values?: Partial<T>;
  data?: unknown;
};

License

MIT