inertia-rails-forms

Inertia Rails Forms

Full-stack form handling for Inertia.js + Rails.

Before building a form, ask:

• Simple create/edit? → <Form> component (no state management needed)
• Requires per-field UI elements? → Still <Form>. React useState for UI state (preview URL, file size display) is independent of form data — <Form> handles the submission; useState handles the UI.
• Multi-step wizard, dynamic fields (add/remove inputs), or form data shared with sibling components (e.g., live preview panel)? → useForm hook
• Tempted by react-hook-form? → Don't. Inertia's <Form> already handles CSRF tokens, redirect following, error mapping from Rails, processing state, file upload detection, and history state. react-hook-form would duplicate or fight all of this.

When NOT to use <Form> or useForm:

• Data lookups — not a form submission. Use router.get with debounce + preserveState, or raw fetch for large datasets
• Inline single-field edits without navigation – router.patch directly, or useForm if you need error display on the field

NEVER:

• Use react-hook-form, vee-validate, or sveltekit-superforms — Inertia <Form> already handles CSRF, redirect following, error mapping, processing state, and file detection. These libraries fight Inertia's request lifecycle.
• Pass data={...} to <Form> — it has no data prop. Data comes from input name attributes automatically. data is a useForm concept.
• Use useForm for simple create/edit — <Form> handles these without state management. Reserve useForm for multi-step wizards, dynamic add/remove fields, or form data shared with sibling components.
• Use controlled value= instead of defaultValue on inputs — controlled inputs bypass <Form>'s dirty tracking, making isDirty always false.
• Omit value="1" on checkboxes — without it, the browser submits "on" and Rails won't cast to boolean correctly.
• Call useForm inside a loop or conditional — it's a hook (React rules apply). Create one form instance per logical form.

<Form> Component (Preferred)

The simplest way to handle forms. Collects data from input name attributes automatically — no manual state management needed. <Form> has NO data prop — do NOT pass data={...} (that's a useForm concept). For edit forms, use defaultValue on inputs.

Use render function children {({ errors, processing }) => (...)} to access form state. Plain children work but give no access to errors, processing, or progress.

import { Form } from '@inertiajs/react'
 
export default function CreateUser() {

Delete Form

Key Render Function Properties

Additional <Form> props (errorBag, only, resetOnSuccess, event callbacks like onBefore, onSuccess, onError, onProgress) are documented in references/advanced-forms.md — see loading trigger below.

Edit Form (Pre-populated)

Use method="patch" and uncontrolled defaults:

• Text/textarea → defaultValue
• Checkbox/radio → defaultChecked
• Select → defaultValue on <select>

Checkbox without explicit value submits "on" — set value="1" so Rails casts to boolean correctly.

Transforming Data

Use the transform prop to reshape data before submission without useForm.

For advanced transform with useForm, see references/advanced-forms.md.

External Access with formRef

The ref exposes the same methods and state as render function props (FormComponentSlotProps). Use when you need to interact with the form from outside <Form>. Key ref methods: submit(), reset(), clearErrors(), setError(), getData(), getFormData(), validate(), touch(), defaults(). State: errors, processing, progress, isDirty, hasErrors, wasSuccessful, recentlySuccessful.

useForm Hook

Use useForm only for multi-step wizards, dynamic add/remove fields, or form data shared with sibling components.

MANDATORY — READ ENTIRE FILE when using useForm hook, transform, errorBag, resetOnSuccess, multi-step forms, or client-side validation with setError: references/advanced-forms.md (~330 lines) — full useForm API, transform examples, error bag scoping, multi-step wizard patterns, and client-side validation.

Do NOT load advanced-forms.md when using <Form> component for simple create/edit forms — the examples above are sufficient.

File Uploads

Both <Form> and useForm auto-detect files and switch to FormData. Upload progress is built into the render function — destructure progress alongside errors and processing:

Choosing <Form> vs useForm for uploads:

• File submits with other fields (avatar + name, one Save button) → file input inside <Form>
• Standalone immediate upload (uploads on select, no Save button) → <Form> + formRef.submit() on change
• Drag-and-drop upload → useForm (dropped files aren't in DOM inputs, setData is cleaner)

Preview / validation → useState alongside either approach, see references/file-uploads.md.

Vue / Svelte

All examples above use React syntax. For Vue 3 or Svelte equivalents:

• Vue 3: references/vue.md — <Form> with #default scoped slot, useForm returns reactive proxy (form.email not setData), v-model binding
• Svelte: references/svelte.md — <Form> with {#snippet} syntax, useForm returns Writable store ($form.email), bind:value, ref exposes methods only (not reactive state)

MANDATORY — READ THE MATCHING FILE when the project uses Vue or Svelte.

Troubleshooting

Related Skills

• Server-side PRG & errors → inertia-rails-controllers (redirect_back, to_hash, flash)
• shadcn inputs → shadcn-inertia (Input/Select adaptation, toast UI)
• Page props typing → inertia-rails-typescript (type Props not interface, TS2344)

MANDATORY — READ ENTIRE FILE when handling file uploads with image preview, Active Storage, or direct uploads: references/file-uploads.md (~200 lines) — image preview with <Form>, Active Storage integration, direct upload setup, multiple files, and progress tracking.