Hooks API

import { useAction } from "next-safe-action/hooks";

const { execute, result, status, ... } = useAction(safeActionFn, callbacks?);

"use client";

import { useAction } from "next-safe-action/hooks";
import { createUser } from "./actions";

export function CreateUserForm() {
	const { execute, result, isPending, hasSucceeded, hasErrored } = useAction(createUser, {
		onSuccess: ({ data }) => {
			console.log("Created user:", data.id);
		},
		onError: ({ error }) => {
			console.error("Failed:", error.serverError);
		},
	});

	return (
		<form onSubmit={(e) => {
			e.preventDefault();
			execute({ name: "John", email: "john@example.com" });
		}}>
			{/* hasErrored narrows result: data is undefined, errors may be present */}
			{hasErrored && result.validationErrors?.name && (
				<p>{result.validationErrors.name._errors[0]}</p>
			)}
			<button disabled={isPending}>
				{isPending ? "Creating..." : "Create User"}
			</button>
			{/* hasSucceeded narrows result: data is guaranteed present */}
			{hasSucceeded && <p>Created user: {result.data.id}</p>}
		</form>
	);
}

import { useOptimisticAction } from "next-safe-action/hooks";

const { execute, optimisticState, ... } = useOptimisticAction(safeActionFn, utils);

"use client";

import { useOptimisticAction } from "next-safe-action/hooks";
import { toggleTodo } from "./actions";

export function TodoItem({ todo }: { todo: Todo }) {
	const { execute, optimisticState } = useOptimisticAction(toggleTodo, {
		currentState: todo,
		updateFn: (state, input) => ({
			...state,
			completed: !state.completed,
		}),
	});

	return (
		<li
			style={{ textDecoration: optimisticState.completed ? "line-through" : "none" }}
			onClick={() => execute({ id: todo.id })}
		>
			{optimisticState.title}
		</li>
	);
}

import { useStateAction } from "next-safe-action/hooks";

const { execute, executeAsync, formAction, result, status, reset, ... } = useStateAction(safeStatefulActionFn, opts?);

"use client";

import { useStateAction } from "next-safe-action/hooks";
import { updateProfile } from "./actions";

export function ProfileForm() {
	const { formAction, result, isPending, hasSucceeded, reset } = useStateAction(updateProfile, {
		initResult: {},
		onSuccess: ({ data }) => {
			console.log("Profile updated:", data);
		},
		onError: ({ error }) => {
			console.error("Failed:", error.serverError);
		},
		onNavigation: ({ navigationKind }) => {
			console.log("Navigation:", navigationKind);
		},
	});

	return (
		<form action={formAction}>
			<input name="name" placeholder="Name" />
			{result.validationErrors?.name && <p>{result.validationErrors.name._errors[0]}</p>}
			<button disabled={isPending}>
				{isPending ? "Saving..." : "Save Profile"}
			</button>
			{hasSucceeded && <p>Saved!</p>}
			<button type="button" onClick={reset}>Reset</button>
		</form>
	);
}

type HookActionStatus =
	| "idle"           // No action executed yet (or after reset)
	| "executing"      // Action is running on the server
	| "hasSucceeded"   // Action completed with data, no errors
	| "hasErrored"     // Action completed with errors
	| "hasNavigated";  // Navigation function was called

type HookShorthandStatus = {
	isIdle: boolean;
	isExecuting: boolean;
	isTransitioning: boolean;
	isPending: boolean;       // isExecuting || isTransitioning
	hasSucceeded: boolean;
	hasErrored: boolean;
	hasNavigated: boolean;
};