DocsPluginsShowcaseReleases
npmStar us on GitHub

Getting Started

IntroductionInstallationProject StructureLayouts and PagesLinking and Navigating

Routing

Folder-Based RoutingFile-Based RoutingDynamic RoutesParallel RoutesIntercepting RoutesCatch-All RoutesMDX & Markdown Pages

Special Files

Loading UIError BoundariesTemplateDefaultNot Found

Data Fetching

LoadersActionsAccessing Route Data

Metadata

Metadata & SEOOpen Graph & TwitterIcons & Favicons

API Routes

API Routes OverviewPlain Function HandlersHono IntegrationDynamic API Routes

Environment Variables

OverviewPrefixes & Client ExposureUsing in API Routes

Styling

CSS OverviewTailwind CSSCSS Modules

Platforms

WebWindowsmacOSLinuxAndroidiOS

Deployment

Deployment OverviewProduction ServerStatic ExportHosting Providers

A native React framework for building cross-platform applications from a single codebase.

Resources

  • Documentation
  • Plugins
  • Showcase
  • Releases

Community

  • GitHub Discussions
  • Reddit
  • Discord
  • LinkedIn

More

  • npm
  • GitHub
  • Issues
  • License

© 2026 Bini Cooperation.

Actions

Experimental

Handle form submissions and data mutations with action exports and useActionData().

Overview

An action is a function exported from a page that handles data mutations, typically from a <Form> submission. React Router runs the action, returns the result, and makes it available to the page via useActionData().

app
contact
page.tsx
/contact
ExportTypeWhen it runs
actionfunction (async or sync)On form submission or POST/PUT/DELETE
loaderfunction (async or sync)Before the route renders (GET)
shouldRevalidatefunctionBefore a revalidation
Actions run on the client in Bini.js (pure SPA). During vite build, routes with an action are marked clientOnly and get a shell page instead of pre-rendered HTML.

Creating an Action

Export a function called action from your page. It receives the request context (including the submitted FormData). Return any serializable value.

src/app/contact/page.tsx
export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')
  const message = formData.get('message')

  // Process the submission
  return { ok: true, email }
}

export default function Contact() {
  return (
    <Form method="post">
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Send</button>
    </Form>
  )
}

Accessing Action Data

Call useActionData() inside the page component to read the action's return value. It is undefined until the action runs for the first time.

src/app/contact/page.tsx
export default function Contact() {
  const result = useActionData()

  return (
    <Form method="post">
      {/* ...inputs... */}
      {result?.ok && <p>Thanks, {result.email}!</p>}
      <button type="submit">Send</button>
    </Form>
  )
}
HookWhat it returns
useActionData()The route's action return value, or undefined
useNavigation()The current submission state (idle, submitting, loading)
useSubmit()Programmatically submit a form

Handling Errors

A thrown error inside an action is caught by the nearest error.tsx boundary, the same way loader and render errors are.

src/app/contact/page.tsx
export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')

  if (!email) {
    throw new Error('Email is required')
  }

  // Process the submission
  return { ok: true }
}

Progressive Enhancement

Actions work with native HTML forms even when JavaScript is disabled (or before hydration finishes), as long as you use React Router's <Form> component instead of a plain <form>.

src/app/contact/page.tsx
import { Form } from 'react-router-dom'

export default function Contact() {
  return (
    <Form method="post">
      <input name="email" type="email" required />
      <button type="submit">Send</button>
    </Form>
  )
}
Plain <form> tags do not trigger actions on client-side navigation. Use <Form> from react-router-dom for any form that submits to an action.

Client-only Routes

Routes with an action are marked clientOnly, the same as routes with a loader. During vite build, the build tool writes a shell page for them because React Router does not run actions or loaders during static rendering.

Route typeSSG outputWhat renders on first visit
No actionFull pre-rendered HTMLInstant paint from HTML
With actionShell page (empty #root)Client renders, then the form works

Complete Example

app
contact
page.tsx
error.tsx
/contact
src/app/contact/page.tsx
import { Form, useActionData, useNavigation } from 'react-router-dom'

export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')
  const message = formData.get('message')

  if (!email || !message) {
    throw new Error('All fields are required')
  }

  await sendMessage({ email, message })
  return { ok: true }
}

export default function Contact() {
  const result = useActionData()
  const navigation = useNavigation()
  const submitting = navigation.state === 'submitting'

  return (
    <Form method="post">
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit" disabled={submitting}>
        {submitting ? 'Sending…' : 'Send'}
      </button>
      {result?.ok && <p>Thanks!</p>}
    </Form>
  )
}

Loaders

Fetch data before a route renders.

Accessing Route Data

Access loader data and navigation state.

Error Boundaries

Catch render errors and show a fallback UI.

API Routes

Add backend endpoints with plain functions or a full Hono app.

Loading UI

Show a fallback while pages and layouts load.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousLoaders
NextAccessing Route Data

On this page

  • Overview
  • Creating an Action
  • Accessing Action Data
  • Handling Errors
  • Progressive Enhancement
  • Client-only Routes
  • Complete Example
Edit this page on GitHub

Actions

Experimental

Handle form submissions and data mutations with action exports and useActionData().

Overview

An action is a function exported from a page that handles data mutations, typically from a <Form> submission. React Router runs the action, returns the result, and makes it available to the page via useActionData().

app
contact
page.tsx
/contact
ExportTypeWhen it runs
actionfunction (async or sync)On form submission or POST/PUT/DELETE
loaderfunction (async or sync)Before the route renders (GET)
shouldRevalidatefunctionBefore a revalidation
Actions run on the client in Bini.js (pure SPA). During vite build, routes with an action are marked clientOnly and get a shell page instead of pre-rendered HTML.

Creating an Action

Export a function called action from your page. It receives the request context (including the submitted FormData). Return any serializable value.

src/app/contact/page.tsx
export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')
  const message = formData.get('message')

  // Process the submission
  return { ok: true, email }
}

export default function Contact() {
  return (
    <Form method="post">
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit">Send</button>
    </Form>
  )
}

Accessing Action Data

Call useActionData() inside the page component to read the action's return value. It is undefined until the action runs for the first time.

src/app/contact/page.tsx
export default function Contact() {
  const result = useActionData()

  return (
    <Form method="post">
      {/* ...inputs... */}
      {result?.ok && <p>Thanks, {result.email}!</p>}
      <button type="submit">Send</button>
    </Form>
  )
}
HookWhat it returns
useActionData()The route's action return value, or undefined
useNavigation()The current submission state (idle, submitting, loading)
useSubmit()Programmatically submit a form

Handling Errors

A thrown error inside an action is caught by the nearest error.tsx boundary, the same way loader and render errors are.

src/app/contact/page.tsx
export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')

  if (!email) {
    throw new Error('Email is required')
  }

  // Process the submission
  return { ok: true }
}

Progressive Enhancement

Actions work with native HTML forms even when JavaScript is disabled (or before hydration finishes), as long as you use React Router's <Form> component instead of a plain <form>.

src/app/contact/page.tsx
import { Form } from 'react-router-dom'

export default function Contact() {
  return (
    <Form method="post">
      <input name="email" type="email" required />
      <button type="submit">Send</button>
    </Form>
  )
}
Plain <form> tags do not trigger actions on client-side navigation. Use <Form> from react-router-dom for any form that submits to an action.

Client-only Routes

Routes with an action are marked clientOnly, the same as routes with a loader. During vite build, the build tool writes a shell page for them because React Router does not run actions or loaders during static rendering.

Route typeSSG outputWhat renders on first visit
No actionFull pre-rendered HTMLInstant paint from HTML
With actionShell page (empty #root)Client renders, then the form works

Complete Example

app
contact
page.tsx
error.tsx
/contact
src/app/contact/page.tsx
import { Form, useActionData, useNavigation } from 'react-router-dom'

export async function action({ request }: { request: Request }) {
  const formData = await request.formData()
  const email = formData.get('email')
  const message = formData.get('message')

  if (!email || !message) {
    throw new Error('All fields are required')
  }

  await sendMessage({ email, message })
  return { ok: true }
}

export default function Contact() {
  const result = useActionData()
  const navigation = useNavigation()
  const submitting = navigation.state === 'submitting'

  return (
    <Form method="post">
      <input name="email" type="email" required />
      <textarea name="message" required />
      <button type="submit" disabled={submitting}>
        {submitting ? 'Sending…' : 'Send'}
      </button>
      {result?.ok && <p>Thanks!</p>}
    </Form>
  )
}

Loaders

Fetch data before a route renders.

Accessing Route Data

Access loader data and navigation state.

Error Boundaries

Catch render errors and show a fallback UI.

API Routes

Add backend endpoints with plain functions or a full Hono app.

Loading UI

Show a fallback while pages and layouts load.

Static Export

How every route is pre-rendered to HTML at build time.

Was this helpful?
PreviousLoaders
NextAccessing Route Data

On this page

  • Overview
  • Creating an Action
  • Accessing Action Data
  • Handling Errors
  • Progressive Enhancement
  • Client-only Routes
  • Complete Example
Edit this page on GitHub