A Next.js Link wrapped in a button behaves strangely
unexpected behavior of Next/Link when it is a child of a buttonShort answer
next/link renders an a element with an href. HTML does not allow interactive content such as a link inside a button, so the markup is invalid and the behaviour of a click on it is not defined. Style the Link itself as a button, or keep the button and call router.push from its click handler.
Fix it fast
1Find out which cause you have
Look at the rendered markup in the browser tools. An a tag inside a button tag is the problem.
grep -rn -B1 -A3 "<button" app components src 2>/dev/null | grep -n "Link"2Match what you see, then jump to its fix
What does the error look like?
unexpected behavior of Next/Link when it is a child of a button<button><a href> nested interactive content
Cause 1 of 2
The Link is a descendant of a button element
1Check
The HTML standard says a button must have no interactive content descendant, and a link with an href is interactive content. Next.js documents that Link extends the a element.
grep -rn "<button" -A2 app components | grep "<Link"2Fix
Put the button styles on the Link itself, so one element does the job.
import Link from 'next/link'
export default function Cta() {
return (
<Link href="/dashboard" className="btn btn-primary">
Dashboard
</Link>
)
}3Verify
Inspect the output: one a element, no button around it.
curl -s http://localhost:3000 | grep -o "<a[^>]*btn[^>]*>"Confirmed by html.spec.whatwg.org
Cause 2 of 2
The control must be a real button that also navigates
1Check
A real button is right when it does an action as well. Then it should navigate in its handler instead of wrapping a Link.
grep -rn "useRouter" app components2Fix
Keep the button and call router.push from a Client Component.
'use client'
import { useRouter } from 'next/navigation'
export default function SaveButton() {
const router = useRouter()
return (
<button type="button" onClick={() => router.push('/dashboard')}>
Save and open dashboard
</button>
)
}3Verify
Click the button: the URL changes without a full reload.
console.log(window.location.pathname)Confirmed by nextjs.org
How do I stop it coming back?
- Use a link for going somewhere and a button for doing something; do not nest one in the other.
- Share one button style class between a and button elements so both look the same.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
next/link throws React.Children.only on its children
Error: React.Children.only expected to receive a single React element child.
React.Children.only accepts exactly one React element and throws for anything else, including an array with one item.
3 causes, each with a fixWeb apps
ESLint says an element in a list is missing its key prop
react/jsx-key
react/jsx-key fires when an element returned from map, Array.from or an array literal has no key.
3 causes, each with a fixWeb apps
There is no tailwind.config.js after installing Tailwind 4 and HeroUI in Next.js
HeroUI components render unstyled
Nothing is broken: Tailwind CSS 4 is configured in CSS and no longer creates tailwind.config.js.
3 causes, each with a fixWeb apps
react-i18next shows the wrong plural form for a count, or prints the key instead of the text
t('item') prints the key item instead of a translated sentence
i18next picks a plural from the count option and looks for keys ending in _one, _other and so on.
4 causes, each with a fixWeb apps
useSession throws because there is no SessionProvider above it
[next-auth]: `useSession` must be wrapped in a <SessionProvider />
useSession reads the session from React Context, and SessionProvider is what creates that context.
3 causes, each with a fixWeb apps
Hydration failed after adding next-themes dark mode
Console reports a server and client mismatch on the html element
next-themes changes the html element and knows the theme only in the browser, so server HTML and client HTML differ.
3 causes, each with a fix