Support navigation attributes in SPA

Author: brophdawg11

demos/spa/app/actions/controller.tsx

@@ -16,15 +16,18 @@ export default createController(routes, {
     },
 
     async greet(context) {
-      let name = ''
-      if (context.request.method === 'POST') {
+      let isSubmission = context.request.method === 'POST'
+      let name = 'friend'
+      if (isSubmission) {
         let formData = await context.request.formData()
         let value = formData.get('name')
-        name = typeof value === 'string' ? value.trim() : ''
+        if (typeof value === 'string' && value.trim() !== '') {
+          name = value.trim()
+        }
       }
 
       await sleep(1000, context.request.signal)
-      return <GreetingPage name={name || 'friend'} />
+      return <GreetingPage isSubmission={isSubmission} name={name} />
     },
   },
 })
@@ -66,10 +69,10 @@ function AboutPage() {
   )
 }
 
-function GreetingPage(handle: Handle<{ name: string }>) {
+function GreetingPage(handle: Handle<{ isSubmission: boolean; name: string }>) {
   return () => (
     <article>
-      <p mix={eyebrowStyle}>Form submitted</p>
+      {handle.props.isSubmission ? <p mix={eyebrowStyle}>Form submitted</p> : null}
       <h1 mix={titleStyle}>Hello, {handle.props.name}!</h1>
       <p mix={bodyStyle}>
         POST submissions expose the Navigation API's form data through{' '}

demos/spa/app/ui/layout.tsx

@@ -44,6 +44,13 @@ export function Layout(handle: Handle<LayoutProps>) {
               >
                 About
               </a>
+              <a
+                href={routes.greet.href()}
+                aria-current={router.active.pathname === routes.greet.href() ? 'page' : undefined}
+                mix={navLinkStyle}
+              >
+                Greet
+              </a>
             </nav>
           </header>
           <main aria-busy={isPending} mix={mainStyle}>

packages/remix/.changes/minor.ui.spa.md

@@ -1 +1 @@
-Export an `SPA` component and `createSPA` setup utility from `remix/ui/spa` that render router outputs during client-side navigation.
+Export an `SPA` component and `createSPA` setup utility from `remix/ui/spa` that render router outputs during client-side navigation and respect `rmx-document` and `rmx-history` navigation attributes.

packages/ui/.changes/minor.spa.md

@@ -1,4 +1,4 @@
-Export an `SPA` component and `createSPA` setup utility from `remix/ui/spa` that render same-origin browser navigations through a URL-to-`RemixNode` router, expose active and pending URLs, forward cancellation signals, and dispatch intercepted form submissions with their `FormData`.
+Export an `SPA` component and `createSPA` setup utility from `remix/ui/spa` that render same-origin browser navigations through a URL-to-`RemixNode` router, expose active and pending URLs, forward cancellation signals, dispatch intercepted form submissions with their `FormData`, and respect `rmx-document` and `rmx-history` navigation attributes.
 
 ```tsx
 import { createRouter } from 'remix/router'

packages/ui/src/runtime/navigation-event.ts

@@ -0,0 +1,76 @@
+type SourceElementNavigateEvent = NavigateEvent & {
+  sourceElement?: Element | null
+}
+
+interface NavigationPrecommitControllerLike {
+  redirect(url: string, options: { history: 'replace' }): void
+}
+
+interface NavigationInterceptOptionsWithPrecommit extends NavigationInterceptOptions {
+  precommitHandler(controller: NavigationPrecommitControllerLike): void
+}
+
+export type NavigationReplacement =
+  | {
+      type: 'navigation'
+      state?: unknown
+    }
+  | {
+      type: 'form-submission'
+      info: unknown
+      state?: unknown
+    }
+
+export function getLinkNavigationElement(event: NavigateEvent): Element | undefined {
+  let sourceElement = (event as SourceElementNavigateEvent).sourceElement
+  if (!(sourceElement instanceof Element)) return
+
+  let linkElement = sourceElement.closest('a, area')
+  return linkElement instanceof Element ? linkElement : undefined
+}
+
+export function getReplaceHistory(value: string | null, defaultValue: boolean): boolean {
+  if (value === 'replace') return true
+  if (value === 'push') return false
+  return defaultValue
+}
+
+export function interceptNavigation(
+  event: NavigateEvent,
+  options: {
+    handler(): Promise<void>
+    replacement: NavigationReplacement | undefined
+  },
+): void {
+  let replacement = options.replacement
+  if (replacement == null) {
+    event.intercept({ handler: options.handler })
+    return
+  }
+
+  if (
+    replacement.type === 'form-submission' &&
+    typeof Reflect.get(window, 'NavigationPrecommitController') === 'function'
+  ) {
+    let interceptOptions: NavigationInterceptOptionsWithPrecommit = {
+      handler: options.handler,
+      precommitHandler(controller) {
+        controller.redirect(event.destination.url, { history: 'replace' })
+      },
+    }
+    event.intercept(interceptOptions)
+    return
+  }
+
+  if (event.cancelable) {
+    event.preventDefault()
+    window.navigation.navigate(event.destination.url, {
+      history: 'replace',
+      info: replacement.type === 'form-submission' ? replacement.info : undefined,
+      state: replacement.state,
+    })
+    return
+  }
+
+  event.intercept({ handler: options.handler })
+}

packages/ui/src/runtime/navigation.ts

@@ -1,14 +1,11 @@
 import { getTopFrame, getNamedFrame } from './run.ts'
 import { createFormNavigationResolver, type FormSubmission } from './form-navigation.ts'
-
-interface NavigationPrecommitControllerLike {
-  redirect(url: string, options: { history: 'replace' }): void
-}
-
-interface NavigationInterceptOptionsWithPrecommit extends NavigationInterceptOptions {
-  handler(): Promise<void>
-  precommitHandler(controller: NavigationPrecommitControllerLike): void
-}
+import {
+  getLinkNavigationElement,
+  getReplaceHistory,
+  interceptNavigation,
+  type NavigationReplacement,
+} from './navigation-event.ts'
 
 type NavigationState = {
   target: string | undefined
@@ -17,10 +14,6 @@ type NavigationState = {
   $rmx: true
 }
 
-type SourceElementNavigateEvent = NavigateEvent & {
-  sourceElement?: Element | null
-}
-
 type RuntimeNavigation = {
   state: NavigationState
   getSubmission?: () => Promise<FormSubmission>
@@ -155,50 +148,22 @@ export function startNavigationListenerImpl(
         }
       }
 
-      if (runtimeNavigation.getSubmission) {
-        // <form method="post"> navigations
-        if (runtimeNavigation.replaceHistory && replayedSubmission == null) {
-          let supportsPrecommit =
-            typeof Reflect.get(window, 'NavigationPrecommitController') === 'function'
-
-          // Modern browsers allow you to update the in-flight navigation entry before it's committed
-          if (supportsPrecommit) {
-            let interceptOptions: NavigationInterceptOptionsWithPrecommit = {
-              handler,
-              precommitHandler(controller) {
-                controller.redirect(event.destination.url, { history: 'replace' })
-              },
-            }
-            event.intercept(interceptOptions)
-            return
-          }
-
-          // Safari doesn't support precommit as of Aug 2026, so we do a full replacement navigation
-          if (event.cancelable) {
-            event.preventDefault()
-            window.navigation.navigate(event.destination.url, {
-              history: 'replace',
+      let replacement: NavigationReplacement | undefined
+      if (runtimeNavigation.replaceHistory && replayedSubmission == null) {
+        replacement = runtimeNavigation.getSubmission
+          ? {
+              type: 'form-submission',
               state,
               info: {
                 type: formSubmissionNavigationInfoType,
                 state,
                 getSubmission: runtimeNavigation.getSubmission,
               } satisfies FormSubmissionNavigationInfo,
-            })
-            return
-          }
-        }
-
-        event.intercept({ handler })
-      } else {
-        // <a>/<form method="get"> navigations
-        if (runtimeNavigation.replaceHistory && event.cancelable) {
-          event.preventDefault()
-          navigation.navigate(event.destination.url, { history: 'replace', state })
-        } else {
-          event.intercept({ handler })
-        }
+            }
+          : { type: 'navigation', state }
       }
+
+      interceptNavigation(event, { handler, replacement })
     },
     { signal },
   )
@@ -275,12 +240,8 @@ function getSourceElementNavigation(
   event: NavigateEvent,
   resolveFormNavigation: ReturnType<typeof createFormNavigationResolver>,
 ): RuntimeNavigation | undefined {
-  let sourceEvent = event as SourceElementNavigateEvent
-  let sourceElement = sourceEvent.sourceElement
-  if (!(sourceElement instanceof Element)) return
-
-  let linkElement = sourceElement.closest('a, area')
-  if (linkElement instanceof Element) {
+  let linkElement = getLinkNavigationElement(event)
+  if (linkElement) {
     if (linkElement.hasAttribute('rmx-document')) return
     if (linkElement.hasAttribute('download')) return
 
@@ -316,9 +277,3 @@ function getSourceElementNavigation(
     getSubmission: formNavigation.getSubmission,
   }
 }
-
-function getReplaceHistory(value: string | null, defaultValue: boolean): boolean {
-  if (value === 'replace') return true
-  if (value === 'push') return false
-  return defaultValue
-}

packages/ui/src/spa/README.md

@@ -22,6 +22,8 @@ root.render(<SPA router={router} fallback="Loading…" />)
 
 `SPA` intercepts same-origin browser navigations, exposes the active and pending URLs through its component context, and forwards navigation cancellation to `router.fetch(url, { signal })`. It preserves the native method for intercepted form submissions and forwards `FormData` as the body of non-GET requests.
 
+Add `rmx-document` to a link or form to bypass SPA interception. Use `rmx-history="push|replace"` to override whether the navigation pushes or replaces the current history entry.
+
 Use `createSPA` in the setup scope of a custom top-level component when it needs to compose the rendered node or navigation state:
 
 ```tsx