useActionState와 useFormStatus

useActionState(action, initialState)는 제출 과정에서 서버 액션의 상태를 추적하도록 감싸는 리액트 19의 훅입니다. 액션 함수와 초기 상태 값을 받아 전체 폼 경험을 구동하는 데 사용할 수 있는 튜플을 반환합니다.

이 훅은 [state, formAction, isPending]를 반환합니다. state에는 액션이 가장 최근에 반환한 값이 저장됩니다(null 또는 사용자가 지정한 초기 값으로 시작). formAction은 폼에 전달할 래핑된 액션입니다. isPending은 액션이 서버에서 실행되는 동안 true입니다.

폼이 제출될 때마다 서버 액션이 실행되고, 반환값이 새로운 state가 됩니다. 처음 렌더링할 때 state는 initialState와 같습니다. 따라서 이전 제출이 있었는지와 그 결과가 무엇이었는지에 따라 서로 다른 화면을 간단하게 표시할 수 있습니다.

서버 액션이 { errors: { email: 'Invalid email' } }을 반환하면 다음과 같이 오류를 인라인으로 표시할 수 있습니다: {state.errors?.email && <p>{state.errors.email}</p>}. 상태는 다시 렌더링되는 동안 유지되므로, 다음 제출이 성공하여 상태를 대체할 때까지 오류 메시지가 계속 표시됩니다.

액션이 { success: true }를 반환하면 컴포넌트에서 다음과 같이 성공 메시지를 렌더링할 수 있습니다: {state?.success && <p>Form submitted!</p>}. 상태 값에 따라 폼을 조건부로 숨기거나 성공 메시지로 바꿀 수 있습니다.

useFormStatus()는 가장 가까운 상위 <form> 요소의 대기 상태를 읽는 훅입니다. 이 훅은 { pending: boolean }을 포함한 객체를 반환합니다. 폼을 렌더링하는 컴포넌트 자체가 아니라 폼의 자식인 컴포넌트 내부에서 사용해야 합니다.

useFormStatus를 폼 내부에서 사용해야 하는 이유는 이 훅이 자신보다 위에 있는 리액트 트리에서 폼의 컨텍스트를 읽기 때문입니다. 폼을 렌더링하는 동일한 컴포넌트에서 호출하면 폼의 자식이 아니라 형제 요소가 되므로 폼의 상태에 접근할 수 없습니다.

표준 패턴은 제출 버튼을 별도의 컴포넌트로 추출하는 것입니다: function SubmitButton() { const { pending } = useFormStatus(); return <button disabled={pending}>Submit</button>; }. 그런 다음 이 컴포넌트를 폼 내부에 배치하면 폼의 대기 상태에 접근할 수 있습니다.

제출 버튼에 disabled={pending}을 설정하면 중복 제출을 방지할 수 있습니다. 사용자가 제출을 클릭하고 서버 액션이 실행되는 동안에는 pending이 true이므로 버튼이 비활성화되어 클릭할 수 없게 됩니다. 액션이 완료되면 pending이 false로 돌아가고 버튼이 다시 활성화됩니다.

완성된 폼 사용자 경험 패턴은 두 훅을 결합합니다. 폼 컴포넌트에서는 useActionState가 액션 결과를 추적하고 formAction을 제공하며, 자식 SubmitButton 컴포넌트 내부에서는 useFormStatus가 대기 상태를 추적합니다. 두 훅을 함께 사용하면 유효성 검사 오류 표시와 반응성 있는 제출 버튼을 구현할 수 있습니다.

더욱 반응성 있는 사용자 경험을 위해 useOptimistic을 useActionState와 함께 사용할 수 있습니다. 서버가 응답하기 전에 예상 결과로 화면을 즉시 업데이트한 다음 실제 응답이 도착하면 조정합니다. 이 패턴은 좋아요 버튼, 할 일 목록 및 빠른 피드백이 필요한 기타 상호작용에서 자주 사용됩니다.

올바르게 작동하려면 useFormStatus를 어디에서 호출해야 합니까?

useActionState(action, initialState)는 서버 액션 결과를 추적하기 위해 [state, formAction, isPending]를 반환합니다. 상태에는 액션의 반환값이 저장되므로 인라인 오류와 성공 메시지를 표시할 수 있습니다. useFormStatus()는 폼의 자식 컴포넌트 내부에서 { pending }을 제공하여 반응성 있는 제출 버튼을 구현할 수 있게 합니다. 두 훅을 함께 사용하면 완전하고 접근성 높은 폼 경험을 만들 수 있습니다.