Inline navigation feedback
Show a shimmer, spinner, or other subtle indicator inside a link while its destination is loading.
Next.js 16+ · Hook
useLinkStatus
useLinkStatus tracks whether a Next.js App Router Link navigation is pending. Use it in a descendant Client Component to render localized inline feedback during slower transitions.
- Since
- 15.3.0
How it works
useLinkStatus provides localized navigation state for a Link. Call it from a Client Component nested inside that Link, then use pending to show brief inline feedback while navigation is blocked or still completing.
Syntax
const { pending } = useLinkStatus()Returns
An object with one boolean property, pending: true before history updates and false after.
Key points
- The hook exposes whether a specific link navigation is currently pending.
- Call it only from a component rendered beneath the relevant Link.
- Disabling prefetch makes inline pending feedback particularly useful.
- The pending flag starts before the history update and ends after it.
- Use route-level loading.js and prefetching as the primary transition mechanisms when appropriate.
Common mistakes
- Do not assume the indicator always appears: prefetched destinations can skip the pending phase.
- Rapid clicks are represented only by the most recently clicked link.
- The hook is for the App Router; it is inert in the Pages Router.
Example: Inline link loading indicator
'use client'
import Link from 'next/link'
import { useLinkStatus } from 'next/link'
function LinkIndicator() {
const { pending } = useLinkStatus()
return <span aria-hidden className={pending ? 'pending' : ''} />
}
export default function Navigation() {
return (
<Link href="/dashboard" prefetch={false}>
Dashboard
<LinkIndicator />
</Link>
)
}Place a Client Component that calls the hook inside a Link descendant. It reads pending to render localized feedback while navigation is waiting; the state becomes false after the browser history update.
When to use it
Unprefetched or dynamic destinations
Provide feedback when a link uses prefetch={false} or its destination cannot immediately render.
Localized transition state
React to navigation state locally without replacing a route-level loading.js fallback.
Interview questions
QWhat does useLinkStatus return?
It returns an object containing pending. That boolean is true before the history update and false afterward, so a nested client component can render localized navigation feedback.
Follow-up: How can the pending phase be made more visible for fast transitions? Add a short initial animation delay and begin the indicator invisible, so it appears only when navigation exceeds that delay.
QHow is the hook scoped to a link?
The hook takes no parameters. It must be called by a descendant component of the Link whose navigation state it should observe.
Follow-up: Where should route-wide loading UI live instead? Prefer the route's loading.js fallback for destination-level loading rather than relying only on an inline indicator.
QWhen is useLinkStatus useful?
It is most useful when Link prefetching is disabled or still in progress, or when a dynamic destination lacks loading.js. In those situations, navigation may have a visible pending interval.
Follow-up: What should be checked before adding this UI? Determine whether production prefetching or loading.js makes the transition effectively instant, because either can remove the visible pending phase.
Related
Linkloading.jsprefetchinguseFormStatus