useActionState는 React 19에서 도입된 비동기 액션의 상태 관리를 위한 Hook이다. 이는 기존의 useFormState가 이름을 바꾸고 기능이 확장된 것으로, 단순히 폼 제출뿐만 아니라 서버와 통신하는 모든 비동기 작업의 결과값(state), 실행 함수(dispatch), 대기 상태(isPending)를 한 번에 관리할 수 있게 해준다.

이전에는 어떻게 처리를 했나 ?

useActionState가 없던 시절, React에서 비동기 폼 처리나 서버와의 상호작용은 개발자가 여러 상태를 직접 관리해야하는 번거로움이 있었다.

useState / useEffect 상태 관리

가장 기본적인 방법으로 폼 제출 상태, 로딩 상태, 에러 상태 등을 각각의 useState로 관리하고, 비동기 작업의 시작과 끝에 맞춰 이들을 수동으로 업데이트해왔다.

function Form() {
  const [formData, setFormData] = useState({ email: '', password: '' });
  const [isLoading, setIsLoading] = useState(false); // 로딩 상태
  const [error, setError] = useState(null); // 에러 상태
  const [successMessage, setSuccessMessage] = useState(''); // 성공 메시지

  const handleSubmit = async e => {
    e.preventDefault();
    setIsLoading(true);
    setError(null);
    setSuccessMessage('');
    // ... API 호출 및 상태 업데이트 로직
  };
  // ...
}

이 방식은 보일러플레이트 코드가 많고, 로딩 및 에러 상태 관리를 개발자가 직접 신경써야 하므로 에러 발생 가능성이 높았다. 또한 여러 폼이나 비동기 작업이 있을 경우 코드의 중복성이 심해진다.

useTransition 로딩 상태 관리

React 18에서 도입된 useTransition Hook은 UI 블로킹 없이 상태 업데이트를 비동기적으로 처리하고, isPending 값을 통해 로딩 상태를 제공했다. 이는 useActionState의 isPending과 유사한 역할을 했지만, 액션의 결과 상태(state)를 직접 관리하지는 않았다.

function Form() {
  const [isPending, startTransition] = useTransition(); // 로딩 상태 관리
  const [message, setMessage] = useState('');

  const handleSubmit = async formData => {
    startTransition(async () => {
      // 비동기 작업을 transition으로 감싸기
      // ... API 호출 및 메시지 설정 로직
      setMessage('완료!');
    });
  };
  //...
}

useTransition은 로딩 상태를 관리하지만, 액션의 결과(성공/실패 데이터)를 컴포넌트 상태로 직접 연결해주지는 않았고 여전히 useState를 사용하여 결과 상태를 별도로 관리해야 했다.

useActionState는 이 두가지 방식의 장점을 결합하여, 비동기 액션의 로딩 상태와 결과 상태를 하나의 Hook으로 통합하여 관리할 수 있게 해준다.

어떻게 효율적으로 사용할 수 있을까 ?

useFormAction 훅은 useActionState의 기능을 확장하여 React Query의 캐시 무효화와 성공/실패 콜백을 통합할 수 있다. 폼 제출 이후 서버 데이터가 변경되면 최신 데이터를 다시 불러와야 하고, 결과에 따라 토스트 알림을 띄우는 등의 사이드 이펙트를 한곳에서 관리하기 위함이다.

useFormAction

원본 액션을 래핑하여 공통 로직(캐시 무효화, 콜백)을 처리하는 훅이다.

import { useQueryClient } from '@tanstack/react-query';
import { useActionState } from 'react';

export function useFormAction<TState, TPayload>(
  action: (prevState: Awaited<TState>, payload: TPayload) => Promise<TState> | TState,
  initialState: Awaited<TState>,
  options?: UseFormActionOptions<Awaited<TState>>
) {
  const queryClient = useQueryClient();

  const wrappedAction = async (prevState: Awaited<TState>, payload: TPayload): Promise<Awaited<TState>> => {
    // 서버 액션 실행
    const result = await action(prevState, payload);

    // 결과에 따른 후속 처리 (Error 발생 여부 체크)
    if (result && typeof result === 'object' && 'error' in result) {
      options?.onError?.(result.error as string);
    } else {
      // 성공 시 캐시 무효화 및 성공 콜백 실행
      if (options?.invalidateKeys) {
        options.invalidateKeys.forEach(key => {
          queryClient.invalidateQueries({ queryKey: key });
        });
      }
      options?.onSuccess?.(result);
    }

    return result as Awaited<TState>;
  };

  return useActionState(wrappedAction, initialState);
}

wrappedAction이 실행되면서 action 호출 → 캐시 갱신(invalidateQueries) → 사용자 알림(onSuccess/onError) 순으로 처리된다.

Zod와 함께 사용

Zod를 이용해 서버와 클라이언트의 유효성 검사 로직을 통합할 수 있다.

'use client';

import { z } from 'zod';
import { useFormAction } from '@/hooks/useFormAction';
import { toast } from 'react-hot-toast';

// Schema 규칙 정의
const RegisterSchema = z.object({
  email: z.string().email('올바른 이메일을 입력해주세요.'),
  password: z.string().min(8, '비밀번호는 8자 이상이어야 합니다.'),
});

// [Server Action]
async function registerUserAction(prevState: any, formData: FormData) {
  const validated = RegisterSchema.safeParse(Object.fromEntries(formData));

  if (!validated.success) {
    return { errors: validated.error.flatten().fieldErrors, success: false };
  }

  // 실제 로직 처리...
  return { success: true, message: '환영합니다!' };
}

//Form 컴포넌트
export function RegisterForm() {
  const [state, formAction, isPending] = useFormAction(
    registerUserAction,
    { message: '', errors: {}, success: false },
    {
      invalidateKeys: [['users']], // 성공 시 유저 목록 캐시 갱신
      onSuccess: res => toast.success(res.message),
      onError: err => toast.error(err),
    }
  );

  return (
    <form action={formAction}>
      <input name="email" placeholder="Email" disabled={isPending} />
      {state.errors?.email && <p>{state.errors.email[0]}</p>}

      <button type="submit" disabled={isPending}>
        {isPending ? '처리 중...' : '가입하기'}
      </button>
    </form>
  );
}

왜 이렇게 사용해야 할까?
실제 프로젝트에서는 데이터의 신선도(Query Invalidation) 와 사용자 피드백(Toast) 이 함께 움직여야 한다. 이렇게 로직을 분리하여 관리하면 아래와 같은 장점이 있다.

커스텀 훅은 인프라 로직(React Query, 공통 에러 처리)을 담당
Zod 스키마는 데이터의 무결성을 보장

결과적으로 코드의 중복은 줄어들고, 어떤 폼에서도 동일한 매커니즘으로 동작하는 환경을 만들 수 있다.

React 19 useActionState 효율적으로 써보기