feat: useLinkStatus (#77300)

# `useLinkStatus` Hook

The `useLinkStatus` hook is primarily useful when:

- Links have `prefetch={false}` set
- Navigation occurs before prefetching has completed
- When React decides to [skip the loading
state](https://react.dev/reference/react/useTransition#preventing-unwanted-loading-indicators)
and #69625

It provides loading state feedback during these navigation transitions,
preventing pages from appearing "frozen" while new content loads.

## Usage

`useLinkStatus` can be called from any descendant component of `Link`
and it returns `{ pending: true }` before history has updated. After the
URL updates, it returns `{ pending: false }`.

```jsx
// When prefetching is disabled
<Link href="/dashboard/reports" prefetch={false}>
  Reports <LoadingIndicator />
</Link>

function LoadingIndicator() {
  const { pending } = useLinkStatus();
  return pending ? <Spinner /> : null;
}
```

## Notes

- If the link has been prefetched, pending change will be skipped and
remain `{ pending: false }`.
- If `useLinkStatus` is not under any `Link`, it will always return `{
pending: false }`.
- `useLinkStatus` currently does not support Pages Router, so it will
always return `{ pending: false }` in Pages Router.
- When you click multiple links in a short period, only the last link's
pending state is shown

---------

Co-authored-by: Andrew Clark <[email protected]>

Author: gaojude

Diff for: packages/next/src/client/app-dir/form.tsx

@@ -16,7 +16,10 @@ import {
   hasUnsupportedSubmitterAttributes,
   type FormProps,
 } from '../form-shared'
-import { mountLinkInstance, unmountLinkInstance } from '../components/links'
+import {
+  mountFormInstance,
+  unmountPrefetchableInstance,
+} from '../components/links'
 
 export type { FormProps }
 
@@ -96,10 +99,10 @@ export default function Form({
   const observeFormVisibilityOnMount = useCallback(
     (element: HTMLFormElement) => {
       if (isPrefetchEnabled && router !== null) {
-        mountLinkInstance(element, actionProp, router, PrefetchKind.AUTO)
+        mountFormInstance(element, actionProp, router, PrefetchKind.AUTO)
       }
       return () => {
-        unmountLinkInstance(element)
+        unmountPrefetchableInstance(element)
       }
     },
     [isPrefetchEnabled, actionProp, router]

Diff for: packages/next/src/client/app-dir/link.tsx

@@ -1,23 +1,25 @@
 'use client'
 
-import type { NextRouter } from '../../shared/lib/router/router'
-
-import React from 'react'
+import React, { createContext, useContext, useOptimistic, useRef } from 'react'
 import type { UrlObject } from 'url'
 import { formatUrl } from '../../shared/lib/router/utils/format-url'
 import { AppRouterContext } from '../../shared/lib/app-router-context.shared-runtime'
-import type { AppRouterInstance } from '../../shared/lib/app-router-context.shared-runtime'
 import { PrefetchKind } from '../components/router-reducer/router-reducer-types'
 import { useMergedRef } from '../use-merged-ref'
 import { isAbsoluteUrl } from '../../shared/lib/utils'
 import { addBasePath } from '../add-base-path'
 import { warnOnce } from '../../shared/lib/utils/warn-once'
+import type { PENDING_LINK_STATUS } from '../components/links'
 import {
+  IDLE_LINK_STATUS,
   mountLinkInstance,
   onNavigationIntent,
-  unmountLinkInstance,
+  unmountLinkForCurrentNavigation,
+  unmountPrefetchableInstance,
+  type LinkInstance,
 } from '../components/links'
 import { isLocalURL } from '../../shared/lib/router/utils/is-local-url'
+import { dispatchNavigateAction } from '../components/app-router-instance'
 
 type Url = string | UrlObject
 type RequiredKeys<T> = {
@@ -228,11 +230,10 @@ function isModifiedEvent(event: React.MouseEvent): boolean {
 
 function linkClicked(
   e: React.MouseEvent,
-  router: NextRouter | AppRouterInstance,
   href: string,
   as: string,
+  linkInstanceRef: React.RefObject<LinkInstance | null>,
   replace?: boolean,
-  shallow?: boolean,
   scroll?: boolean,
   onNavigate?: OnNavigateEventHandler
 ): void {
@@ -278,20 +279,12 @@ function linkClicked(
       }
     }
 
-    // If the router is an NextRouter instance it will have `beforePopState`
-    // TODO: This should access the router methods directly, rather than
-    // go through the public interface.
-    const routerScroll = scroll ?? true
-    if ('beforePopState' in router) {
-      router[replace ? 'replace' : 'push'](href, as, {
-        shallow,
-        scroll: routerScroll,
-      })
-    } else {
-      router[replace ? 'replace' : 'push'](as || href, {
-        scroll: routerScroll,
-      })
-    }
+    dispatchNavigateAction(
+      as || href,
+      replace ? 'replace' : 'push',
+      scroll ?? true,
+      linkInstanceRef.current
+    )
   }
 
   React.startTransition(navigate)
@@ -321,8 +314,12 @@ export default function LinkComponent(
     ref: React.Ref<HTMLAnchorElement>
   }
 ) {
+  const [linkStatus, setOptimisticLinkStatus] = useOptimistic(IDLE_LINK_STATUS)
+
   let children: React.ReactNode
 
+  const linkInstanceRef = useRef<LinkInstance | null>(null)
+
   const {
     href: hrefProp,
     as: asProp,
@@ -557,14 +554,26 @@ export default function LinkComponent(
   // a revalidation or refresh.
   const observeLinkVisibilityOnMount = React.useCallback(
     (element: HTMLAnchorElement | SVGAElement) => {
-      if (prefetchEnabled && router !== null) {
-        mountLinkInstance(element, href, router, appPrefetchKind)
+      if (router !== null) {
+        linkInstanceRef.current = mountLinkInstance(
+          element,
+          href,
+          router,
+          appPrefetchKind,
+          prefetchEnabled,
+          setOptimisticLinkStatus
+        )
       }
+
       return () => {
-        unmountLinkInstance(element)
+        if (linkInstanceRef.current) {
+          unmountLinkForCurrentNavigation(linkInstanceRef.current)
+          linkInstanceRef.current = null
+        }
+        unmountPrefetchableInstance(element)
       }
     },
-    [prefetchEnabled, href, router, appPrefetchKind]
+    [prefetchEnabled, href, router, appPrefetchKind, setOptimisticLinkStatus]
   )
 
   const mergedRef = useMergedRef(observeLinkVisibilityOnMount, childRef)
@@ -606,7 +615,7 @@ export default function LinkComponent(
         return
       }
 
-      linkClicked(e, router, href, as, replace, shallow, scroll, onNavigate)
+      linkClicked(e, href, as, linkInstanceRef, replace, scroll, onNavigate)
     },
     onMouseEnter(e) {
       if (!legacyBehavior && typeof onMouseEnterProp === 'function') {
@@ -671,6 +680,8 @@ export default function LinkComponent(
     childProps.href = addBasePath(as)
   }
 
+  let link: React.ReactNode
+
   if (legacyBehavior) {
     if (process.env.NODE_ENV === 'development') {
       console.error(
@@ -680,12 +691,26 @@ export default function LinkComponent(
           'Learn more: https://nextjs.org/docs/app/building-your-application/upgrading/codemods#remove-a-tags-from-link-components'
       )
     }
-    return React.cloneElement(child, childProps)
+    link = React.cloneElement(child, childProps)
+  } else {
+    link = (
+      <a {...restProps} {...childProps}>
+        {children}
+      </a>
+    )
   }
 
   return (
-    <a {...restProps} {...childProps}>
-      {children}
-    </a>
+    <LinkStatusContext.Provider value={linkStatus}>
+      {link}
+    </LinkStatusContext.Provider>
   )
 }
+
+const LinkStatusContext = createContext<
+  typeof PENDING_LINK_STATUS | typeof IDLE_LINK_STATUS
+>(IDLE_LINK_STATUS)
+
+export const useLinkStatus = () => {
+  return useContext(LinkStatusContext)
+}

Diff for: packages/next/src/client/components/app-router-instance.ts

@@ -24,6 +24,7 @@ import type {
   NavigateOptions,
   PrefetchOptions,
 } from '../../shared/lib/app-router-context.shared-runtime'
+import { setLinkForCurrentNavigation, type LinkInstance } from './links'
 
 export type DispatchStatePromise = React.Dispatch<ReducerState>
 
@@ -235,17 +236,21 @@ function getAppRouterActionQueue(): AppRouterActionQueue {
   return globalActionQueue
 }
 
-function dispatchNavigateAction(
+export function dispatchNavigateAction(
   href: string,
   navigateType: NavigateAction['navigateType'],
-  shouldScroll: boolean
+  shouldScroll: boolean,
+  linkInstanceRef: LinkInstance | null
 ): void {
   // TODO: This stuff could just go into the reducer. Leaving as-is for now
   // since we're about to rewrite all the router reducer stuff anyway.
   const url = new URL(addBasePath(href), location.href)
   if (process.env.__NEXT_APP_NAV_FAIL_HANDLING) {
     window.next.__pendingUrl = url
   }
+
+  setLinkForCurrentNavigation(linkInstanceRef)
+
   dispatchAppRouterAction({
     type: ACTION_NAVIGATE,
     url,
@@ -298,12 +303,12 @@ export const publicAppRouterInstance: AppRouterInstance = {
       },
   replace: (href: string, options?: NavigateOptions) => {
     startTransition(() => {
-      dispatchNavigateAction(href, 'replace', options?.scroll ?? true)
+      dispatchNavigateAction(href, 'replace', options?.scroll ?? true, null)
     })
   },
   push: (href: string, options?: NavigateOptions) => {
     startTransition(() => {
-      dispatchNavigateAction(href, 'push', options?.scroll ?? true)
+      dispatchNavigateAction(href, 'push', options?.scroll ?? true, null)
     })
   },
   refresh: () => {