Safe Action Hooks

next-safe-action/skills/skills/safe-action-hooks

作者 next-safe-actiona2605bd2e84321245cba8f5718c144a6e4a5fa47無授權條款收錄於 2026年10月9日更新於 2026年10月9日

Use when executing next-safe-action actions from React client components or building optimistic UI -- useAction, useOptimisticAction, useStateAction, useOptimisticStateAction, status/callbacks (onSuccess/onError/onSettled), execute vs executeAsync, formAction, reset, and queued or serialized mutations such as drag-to-reorder, Kanban boards, overlapping saves, accumulating changes, and shared pending-change lists

僅含說明Software DevelopmentAI & Agents
AI 產生的概覽

說明如何使用 next-safe-action 的 React hooks 執行伺服器動作、樂觀更新與排隊狀態變更。

功能
這個技能說明 next-safe-action 的 React hooks：useAction、useOptimisticAction、useStateAction 與 useOptimisticStateAction。它解釋各 hook 與對應 action 方法的搭配、共用的回傳值（例如 execute、executeAsync、狀態旗標與 reset），以及 initResult 選項。內容也涵蓋樂觀更新、用於累積寫入的排隊派送、formAction 用法與常見反模式。
適用情境
當你需要從 React 用戶端元件呼叫 next-safe-action 動作、在四個 hook 之間做選擇，或建立樂觀 UI 時使用。它也適合重疊或排隊的變更，例如拖曳排序、看板以及累積式修改。
執行需求
需要一個使用 next-safe-action 函式庫的 React 專案；內容假設採用 Next.js 伺服器動作，表單輸入情境還需要能解析 FormData 的 schema，例如 zod-form-data。這個技能不含指令碼，僅為說明文件。

next-safe-action React Hooks

Import

ts
// All hooksimport {  useAction,  useOptimisticAction,  useStateAction,  useOptimisticStateAction,} from "next-safe-action/hooks";
// Backward-compatible re-export (same useStateAction hook)import { useStateAction } from "next-safe-action/stateful-hooks";

Which Hook

HookAction methodUse for
useAction.action()Programmatic triggers, interactive UI, most cases
useOptimisticAction.action()Instant UI for changes that replace state (last-write-wins)
useStateAction.stateAction()<form action={formAction}>, prevResult on the server, queued dispatches
useOptimisticStateAction.stateAction()Instant UI for changes that accumulate: overlapping writes are queued, each folding over the confirmed state

Pick by action kind first: .action() pairs with useAction / useOptimisticAction, .stateAction() pairs with useStateAction / useOptimisticStateAction.

useAction — Quick Start

tsx
"use client";
import { useAction } from "next-safe-action/hooks";import { createUser } from "@/app/actions";
export function CreateUserForm() {  const { execute, result, status, isExecuting, isPending } = useAction(createUser, {    onSuccess: ({ data }) => {      console.log("User created:", data);    },    onError: ({ error }) => {      console.error("Failed:", error.serverError);    },  });
  return (    <form onSubmit={(e) => {      e.preventDefault();      const formData = new FormData(e.currentTarget);      execute({ name: formData.get("name") as string });    }}>      <input name="name" required />      <button type="submit" disabled={isPending}>        {isPending ? "Creating..." : "Create User"}      </button>      {result.serverError && <p className="error">{result.serverError}</p>}      {result.data && <p className="success">Created: {result.data.id}</p>}    </form>  );}

useOptimisticAction — Quick Start

tsx
"use client";
import { useOptimisticAction } from "next-safe-action/hooks";import { toggleTodo } from "@/app/actions";
export function TodoItem({ todo }: { todo: Todo }) {  const { execute, optimisticState } = useOptimisticAction(toggleTodo, {    currentState: todo,    updateFn: (state, input) => ({      ...state,      completed: !state.completed,    }),  });
  return (    <label>      <input        type="checkbox"        checked={optimisticState.completed}        onChange={() => execute({ todoId: todo.id })}      />      {todo.title}    </label>  );}

useOptimisticStateAction — Quick Start

For overlapping writes that must accumulate (reorder an item, then reorder it again before the first save lands). Dispatches are queued: each waits for the previous to settle, and the server receives the last confirmed state as prevResult.

tsx
"use client";
import { useOptimisticStateAction } from "next-safe-action/hooks";import { moveItem } from "@/app/actions";import { reorder } from "@/lib/reorder"; // the same reducer the server runs
export function ReorderList({ items }: { items: Item[] }) {  const { execute, optimisticState, isPending } = useOptimisticStateAction(moveItem, {    currentState: items, // must be a stable reference — compared by identity    updateFn: reorder,  });
  return (    <ul data-saving={isPending}>      {optimisticState.map((item) => (        <li key={item.id}>          {item.label}          <button onClick={() => execute({ id: item.id, direction: "up" })}>Up</button>        </li>      ))}    </ul>  );}

The action must be a .stateAction(), and must revalidate the state the page renders:

ts
"use server";
export const moveItem = actionClient  .inputSchema(moveSchema)  .stateAction(async ({ parsedInput }, { prevResult }) => {    const next = reorder(prevResult.data!, parsedInput); // always the last confirmed state    await db.items.save(next);    revalidatePath("/items");    return next;  });

See useOptimisticStateAction in depth for the decision rules, the pending-changes-list shape, and the gotchas.

useStateAction — Quick Start

tsx
"use client";
import { useStateAction } from "next-safe-action/hooks";import { submitFeedback } from "@/app/actions";
export function FeedbackForm() {  const { formAction, result, isPending, hasSucceeded } = useStateAction(submitFeedback, {    onSuccess: ({ data }) => {      console.log("Submitted:", data);    },    onError: ({ error }) => {      console.error("Failed:", error.serverError);    },  });
  return (    <form action={formAction}>      <input name="rating" type="number" min="1" max="5" required />      <textarea name="comment" required />      <button type="submit" disabled={isPending}>        {isPending ? "Submitting..." : "Submit"}      </button>      {result.validationErrors?.comment && (        <p className="error">{result.validationErrors.comment._errors[0]}</p>      )}      {hasSucceeded && <p className="success">Thank you!</p>}    </form>  );}

The server-side action must use .stateAction() (not .action()). <form action={formAction}> submits raw FormData, so the input schema must parse FormData (e.g. with zod-form-data):

ts
"use server";
import { z } from "zod";import { zfd } from "zod-form-data";import { actionClient } from "@/lib/safe-action";
export const submitFeedback = actionClient  .inputSchema(    zfd.formData({      rating: zfd.numeric(z.number().min(1).max(5)),      comment: zfd.text(z.string()),    })  )  .stateAction(async ({ parsedInput }, { prevResult }) => {    // prevResult contains the previous SafeActionResult    await db.feedback.create({ data: parsedInput });    return { rating: parsedInput.rating };  });

Return Value

All hooks (useAction, useOptimisticAction, useStateAction, useOptimisticStateAction) return:

PropertyTypeDescription
execute(input)(input) => voidFire-and-forget execution
executeAsync(input)(input) => Promise<Result>Returns a promise with the result
inputInput | undefinedLast input dispatched (via execute, executeAsync, or formAction)
resultSafeActionResultLast action result — discriminated union of 4 branches (idle / success / serverError / validationErrors); narrowed when you check status or any has* shorthand
reset()() => voidResets client state to initial (restores initResult if provided) and ignores the result of any in-flight execution. It does not cancel the server call already in flight. On the queued hooks (useStateAction, useOptimisticStateAction) it also skips every dispatch still waiting its turn: their action never runs and no write happens
statusHookActionStatusCurrent status string
isIdlebooleanNo execution has started yet
isExecutingbooleanAction promise is pending
isTransitioningbooleanReact transition is pending
isPendingbooleanisExecuting || isTransitioning, except after reset(): a reset reports idle immediately, even while the uncancellable transition it interrupted is still settling
hasSucceededbooleanLast execution completed without errors (a void action succeeds with result.data still undefined)
hasErroredbooleanLast execution had serverError, validationErrors, or threw (a raw throw leaves result empty)
hasNavigatedbooleanLast execution triggered a navigation

useOptimisticAction additionally returns: | optimisticState | State | The optimistically-updated state |

useStateAction additionally returns: | formAction | (input) => void | Dispatcher for <form action={formAction}> pattern |

useOptimisticStateAction returns everything useStateAction returns, plus: | optimisticState | State | Confirmed state folded with every in-flight change (always defined) |

The hook return is itself a discriminated union keyed on status and every has* / is* shorthand (each typed as literal true / false per branch). Narrowing any discriminant narrows result — e.g. inside if (hasSucceeded), result.data is Data (not Data | undefined). See Type narrowing via hook status.

initResult Option

All hooks accept initResult to seed the hook with a preloaded result (e.g. data fetched on the server): in the opts object for useAction/useStateAction, in the utils object (alongside currentState/updateFn) for useOptimisticAction/useOptimisticStateAction. The value is captured once at mount (like React's useActionState initial state): later changes to the option are ignored, and reset() restores the mount value. The seeded shape precisely types the idle branch's result. See initResult in depth.

Supporting Docs

  • execute vs executeAsync, result handling
  • useStateAction in depth (decision table, formAction)
  • Optimistic updates with useOptimisticAction
  • useOptimisticStateAction: queued optimistic updates for overlapping writes
  • Status lifecycle and all callbacks
  • throwOnNavigation flag

Anti-Patterns

ts
// BAD: Using executeAsync without try/catch when navigation errors are possibleconst handleClick = async () => {  const result = await executeAsync({ id }); // Throws on redirect!  showToast(result.data);};
// GOOD: Wrap executeAsync in try/catchconst handleClick = async () => {  try {    const result = await executeAsync({ id });    showToast(result.data);  } catch (e) {    // Handle non-navigation errors here if needed, then re-throw    // Navigation errors must propagate to Next.js    throw e;  }};
tsx
// BAD: Last-write-wins for changes that accumulate — the second move builds on stale state,// and the response of the first move is discardedconst { execute } = useOptimisticAction(moveItem, { currentState: items, updateFn: reorder });
// GOOD: Queued dispatches, each folding over the previous resultconst { execute } = useOptimisticStateAction(moveItem, { currentState: items, updateFn: reorder });
ts
// BAD: Using .action() with useStateAction — type errorconst myAction = actionClient.inputSchema(schema).action(async ({ parsedInput }) => { ... });useStateAction(myAction); // TypeScript error!
// GOOD: Use .stateAction() for useStateActionconst myAction = actionClient.inputSchema(schema).stateAction(async ({ parsedInput }, { prevResult }) => { ... });useStateAction(myAction); // Works!

來源與署名

來源：next-safe-action/skills位於skills/safe-action-hooks提交a2605bd

授權條款： 無授權條款

內容歸原作者所有。SourceWeft 從公開儲存庫中收錄這些內容。

檢舉或申請下架

更多來自 next-safe-action/skills 的技能

Safe Action Validation Errors

next-safe-action

說明 next-safe-action 的驗證錯誤結構與輔助函式，用來回傳並顯示欄位層級與表單層級的錯誤。

Software Development2026年10月9日

Safe Action Middleware

next-safe-action

指導實作 next-safe-action 中介軟體，涵蓋驗證、記錄、限流、錯誤處理與內容延伸。

Software Development2026年10月9日

Safe Action Testing

next-safe-action

用於測試 next-safe-action 伺服器動作、中介層、鉤子、驗證錯誤與伺服器錯誤的 Vitest 模式。

Software Development2026年10月9日

Safe Action Client

next-safe-action

指導建立與設定 next-safe-action 用戶端與動作，包含驗證和錯誤處理。

Software Development2026年10月9日

Safe Action Forms

next-safe-action

指導如何將 next-safe-action 與 React 表單整合，包括原生表單、react-hook-form 轉接器與檔案上傳。

Software Development2026年10月9日

Safe Action Better Auth

next-safe-action

為 next-safe-action 伺服器動作加入 Better Auth 工作階段驗證與授權中介軟體。

Software Development2026年10月9日

更多Software Development技能

Playground

anthropics

精選

建立自成一體的互動式 HTML 遊樂場，包含控制項、即時預覽與可複製的提示詞輸出。

Software Development37K今天更新

M5 Onboard

anthropics

精選

透過 USB 偵測 M5Stack ESP32 開發板，燒錄 UIFlow 2.0 韌體並安裝 MicroPython 應用程式套件。

Software Development37K今天更新

Cardputer Buddy

anthropics

精選

指導迭代 Cardputer-Adv 的 MicroPython 應用程式套件：新增應用程式、透過 USB 序列埠推送檔案、查看日誌並執行 REPL 指令。

Software Development37K今天更新

Web Design Guidelines

vercel-labs

精選

依據從遠端來源取得的 Web Interface Guidelines 審查 UI 程式碼，並以 file:line 形式回報問題。

Software Development32K6 週前更新

Vercel React Native Skills

vercel-labs

精選

React Native 與 Expo 最佳實務規則，涵蓋清單效能、動畫、導覽、UI 模式、狀態與 monorepo 設定。

Software Development32K6 週前更新

Vercel React Best Practices

vercel-labs

精選

Vercel 的 React 與 Next.js 效能指南，以 70 條規則的形式用於撰寫、審查與重構程式碼。

Software Development32K6 週前更新