Server Action Form Submission

Forms can be submitted directly to the server using Server Actions. Here's a basic form that shows how to do that with the useFormState hook (see warning below on whether to use that or useActionState):

'use client'
import { useFormState } from 'react-dom'
import { createDeviceAction } from './action'

export function AddDeviceForm() {
  const [state, formAction] = useFormState(createDeviceAction, {
    status: '',
    message: '',
  })

  return (
    <form action={formAction} className="server-actions-simple-form">
      <fieldset>
        <label htmlFor="name">Name:</label>
        <input type="text" name="name" id="name" placeholder="type something" />
        <button type="submit">Submit</button>
      </fieldset>
      {state.status === 'error' && (
        <p className="text-red-500">{state.message}</p>
      )}
      {state.status === 'success' && (
        <p className="text-green-500">{state.message}</p>
      )}
    </form>
  )
}

Live Demo

Here's a live inline demo of this form in action. If you submit it without entering any text, its server action will return an error message. If you enter some text, it will return a success message with an ID for the device you created.

Under the covers, React creates an API endpoint for us, and then provides its own wrapper calls and data structures on both the request and response cycles, leaving us to focus solely on our UI and business logic. It uses our createDeviceAction to automatically create an endpoint, and if you submit the form you will see a POST request being made to whatever url the form is on.

The Server Action that this form submits to is defined in a separate file. This runs on the server, so add a 'use server' directive at the top of the file:

'use server'

export async function createDeviceAction(prevState: any, formData: FormData) {
  const name = formData.get('name')

  if (name) {
    const device = {
      name,
      id: Math.round(Math.random() * 10000),
    }

    return {
      status: 'success',
      message: `Device '${name}' created with ID: ${device.id}`,
      device,
    }
  } else {
    return {
      status: 'error',
      message: 'Name is required',
    }
  }
}

The createDeviceAction function receives the form data and returns an object with a status and message property. The code here is simulating a database mutation and doing some basic validation. If the form data is valid, it also returns a device object. You don't need to use status and message in your form - you can send anything you like back.

Finally, you can render the form in your app (in this case we're rendering the page that contains the form as an RSC):

import { AddDeviceForm } from './form'

export default function SimpleFormPage() {
  return (
    <div>
      <h1>Simple Form</h1>
      <AddDeviceForm />
    </div>
  )
}

One nice thing about this is that the Enter key works on your keyboard without any extra code. This is because the form is a real form, and the submit button is a real submit button. The formAction hook is doing the work of intercepting the form submission and calling the server action instead of the default form submission. It feels more like the old school web.