useActionState란?

useActionState는 Next.js 14에서 도입된 새로운 React 훅으로, 서버 액션(Server Actions)과 함께 사용하여 클라이언트 컴포넌트에서 서버 액션을 호출하고, 그 상태를 관리하는 역할을 한다.

 

🔹 useActionState 개념

• 서버 액션을 클라이언트 컴포넌트에서 사용할 때, 상태(state)를 관리할 수 있도록 해준다.
• 기존 useState와 비슷하지만, 서버 액션의 요청 상태(pending, success, error) 를 다룰 수 있다.

🔹 useActionState 사용법

1️⃣ 서버 액션 정의 (server.ts)

서버 액션은 서버에서 실행될 함수로, use server 디렉티브를 사용한다.

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

export async function submitForm(prevState: any, formData: FormData) {
  const name = formData.get("name") as string;
  if (!name) {
    return { error: "이름을 입력하세요!" };
  }

  return { success: `안녕하세요, ${name}!` };
}

2️⃣ useActionState로 서버 액션 호출 (ClientComponent.tsx)

"use client";

import { useActionState } from "react";
import { submitForm } from "./actions";

export default function ClientComponent() {
  const [state, action, isPending] = useActionState(submitForm, null);

  return (
    <form action={action}>
      <input name="name" placeholder="이름 입력" />

      <button type="submit" disabled={isPending}>
        {isPending ? "전송 중..." : "전송"}
      </button>

      {state?.error && <p style={{ color: "red" }}>{state.error}</p>}
      {state?.success && <p style={{ color: "green" }}>{state.success}</p>}
    </form>
  );
}

 

🔹 useActionState의 동작 방식

1. 사용자가 폼을 제출하면 submitForm 서버 액션이 실행된다.
2. useActionState가 이전 상태(prevState)와 새로운 데이터(formData)를 서버 액션에 전달한다.
3. 서버 액션의 결과(error 또는 success 메시지)가 state에 저장된다.
4. state 값이 업데이트되면서 UI가 자동으로 갱신된다.

 

🔹 isPending이란?

• useActionState가 서버 액션을 실행 중인지 여부를 나타낸다.
• true이면 서버 액션이 진행 중이고,
  false이면 서버 응답을 받아 처리가 완료됨을 의미한다.
• 보통 버튼 비활성화(loading 상태) 또는 로딩 스피너 표시에 사용된다.

 

🔹 isPending 동작 방식

1. 사용자가 폼을 제출하면 action이 실행됨.
2. 서버 액션이 실행되면 isPending이 true로 변경됨 → 버튼이 disabled 처리됨.
3. 서버 응답을 받으면 isPending이 false로 변경됨 → 버튼이 다시 활성화됨.
4. 결과(state.success 또는 state.error에 저장된 값)가 화면에 표시됨.