Skip to main content

useActionState

Check out the official React docs!

For more detailed information about React concepts and APIs, please refer to the official documentation for useActionState.


useActionState keeps state that is updated by an action, for example the result of submitting a form. It returns the current state, a dispatch function that runs the action, and isPending.

The action receives the previous state and the payload passed to dispatch, and returns the next state, either directly or as a promise:

let message, submitAction, isPending =
React.useActionState (
(fun (previousMessage: string) (formData: FormData) -> promise {
// updateName: string -> JS.Promise<string>, returns a message for the user
let! message = updateName (unbox<string> (formData.get "name"))
return message
}),
"" // initial state
)

Html.form [
prop.action submitAction
prop.children [
Html.input [ prop.name "name" ]
Html.button [ prop.type'.submit; prop.disabled isPending; prop.text "Save" ]
]
]

When dispatch is passed to prop.action, the payload is the form's FormData. While an async action runs, isPending is true. If the form is submitted again in the meantime, the actions run one after another.

Show code
module Example.UseActionState

open Fable.Core
open Browser.Types
open Feliz

/// Pretends to update the name on a server. Rejects empty names.
let updateName (name: string) : JS.Promise<Result<string, string>> = promise {
do! Promise.sleep 1000

if System.String.IsNullOrWhiteSpace name then
return Error "Please enter a name."
else
return Ok name
}

[<ReactComponent(true)>]
let UseActionState () =
let message, submitAction, isPending =
React.useActionState (
(fun (_previousMessage: string) (formData: FormData) -> promise {
let! result = updateName (unbox<string> (formData.get "name"))

match result with
| Ok name -> return $"Saved '{name}'."
| Error error -> return error
}),
""
)

Html.form [
// React calls the action with the form's data and resets the input afterwards.
prop.action submitAction
prop.children [
Html.input [ prop.name "name"; prop.placeholder "Your name" ]
Html.button [
prop.type'.submit
prop.disabled isPending
prop.text (if isPending then "Saving..." else "Save")
]
if message <> "" then
Html.p message
]
]

Form actions​

React 19 lets a form call a function instead of navigating to a URL. In Feliz, pass a FormData -> unit or FormData -> JS.Promise<unit> to prop.action:

Html.form [
prop.action (fun (formData: FormData) -> promise {
do! saveComment (unbox<string> (formData.get "comment"))
})
prop.children [
Html.textarea [ prop.name "comment" ]
Html.button [ prop.type'.submit; prop.text "Post" ]
]
]
  • The action runs as a transition, and React resets the form's uncontrolled fields when it finishes.
  • prop.formAction on a submit button overrides the form's action, so one form can have several buttons with different actions.
  • Child components can read the submission state with ReactDOM.useFormStatus.
  • prop.action "/some/url" still works for classic forms.

Dispatching without a form​

dispatch can be called with any payload. Call it inside React.startTransition (or a transition from useTransition) so that isPending updates:

let total, add, isPending = React.useActionState ((fun total (amount: int) -> total + amount), 0)

Html.button [
prop.onClick (fun _ -> React.startTransition (fun () -> add 5))
prop.text $"Total: {total}"
]