react-onsubmit

React

React hook and component for onsubmit.dev. Connect any React form to your onsubmit.dev endpoint with zero dependencies. No backend required.

Installation

bash

npm install react-onsubmit

Quick start

Option A — OnSubmitForm component (recommended)

Drop-in replacement for a plain <form>. Handles loading state, errors, and success message automatically:

tsx

import { OnSubmitForm } from 'react-onsubmit';

export function ContactForm() {
  return (
    <OnSubmitForm formId="YOUR_FORM_ID" successMessage="Thanks! We'll be in touch.">
      <input name="name" placeholder="Your name" required />
      <input name="email" type="email" placeholder="Email" required />
      <textarea name="message" placeholder="Message" />
      <button type="submit">Send</button>
    </OnSubmitForm>
  );
}

Your form ID is available in the onsubmit.dev dashboard after creating a form.

Option B — useOnSubmit hook (full control)

Use the hook when you need to drive your own UI state:

tsx

import { useOnSubmit } from 'react-onsubmit';

export function ContactForm() {
  const { handleSubmit, isLoading, isSuccess, error, reset } = useOnSubmit({
    formId: 'YOUR_FORM_ID',
    onSuccess: (data) => console.log('Submitted!', data),
    onError: (err) => console.error('Failed:', err),
  });

  if (isSuccess) {
    return (
      <div>
        <p>Thanks! We'll be in touch.</p>
        <button onClick={reset}>Send another</button>
      </div>
    );
  }

  return (
    <form onSubmit={handleSubmit}>
      <input name="name" placeholder="Your name" required />
      <input name="email" type="email" placeholder="Email" required />
      {error && <p style={{ color: 'red' }}>{error}</p>}
      <button type="submit" disabled={isLoading}>
        {isLoading ? 'Sending…' : 'Send'}
      </button>
    </form>
  );
}

Component props

OnSubmitForm accepts the following props. All standard HTML <form> attributes are also forwarded to the underlying element.

Prop	Type	Description
formId	string	Required. Your onsubmit.dev form ID.
successMessage	string	Text rendered in place of the form on success.
endpoint	string	Override the default API base URL.
onSuccess	(data: unknown) => void	Called after a successful submission.
onError	(error: unknown) => void	Called when submission fails.

Hook API

Options

Option	Type	Description
formId	string	Required. Your onsubmit.dev form ID.
endpoint	string	Override the default API base URL.
onSuccess	(data: unknown) => void	Called after a successful submission.
onError	(error: unknown) => void	Called when submission fails.

Returns

Property	Type	Description
handleSubmit	(e: FormEvent) => Promise<void>	Pass directly to <form onSubmit={...}>.
isLoading	boolean	true while the request is in flight.
isSuccess	boolean	true after a successful submission.
error	string \| null	Error message, or null if none.
data	unknown	Raw response from the API.
reset	() => void	Resets all state back to initial values.

File uploads

File inputs are handled automatically. When the form contains a file field the data is sent as multipart/form-data. Otherwise JSON is used.

Custom endpoint

Useful for self-hosted deployments:

tsx

<OnSubmitForm formId="YOUR_FORM_ID" endpoint="https://your-instance.example.com/f">
  ...
</OnSubmitForm>

Or with the hook:

const { handleSubmit } = useOnSubmit({
  formId: 'YOUR_FORM_ID',
  endpoint: 'https://your-instance.example.com/f',
});