Inertia Rails Pages

Page components, layouts, navigation, and client-side APIs.

Before building a page, ask:

• Does this page need a layout? → Use persistent layout (React: Page.layout = ...; Vue: defineOptions({ layout }); Svelte: module script export) — wrapping in JSX/template remounts on every navigation, losing scroll position, audio playback, and component state
• Does UI state come from the URL? → Change BOTH controller (read params, pass as prop) AND component (derive from prop, no useState/useEffect) — use router.get to update URL
• Need to refresh data without navigation? → router.reload({ only: [...] }) — never useEffect + fetch
• Need to update a prop without server round-trip? → router.replaceProp — no fetch, no reload

NEVER:

• Parse window.location.search or use useSearchParams — derive URL state from controller props
• Use useState/useEffect to sync URL ↔ React state — the controller passes URL-derived data as props; the component just reads them
• Pass arguments to <Deferred> render function — {(data) => ...} does NOT work; child reads via usePage()
• Access usePage().props.flash — flash is top-level: usePage().flash
• Wrap layout in JSX return for persistence — use Page.layout = ... or global layout inside createInertiaApp's resolve callback

Page Component Structure