The example uses { name: 'ZEIT' } but then say that it will link to `?name=Zeit`. Co-authored-by: JJ Kasper <jj@jjsweb.site>
5.4 KiB
description |
---|
Enable client-side transitions between routes with the built-in Link component. |
next/link
Examples
Before moving forward, we recommend you to read Routing Introduction first.
Client-side transitions between routes can be enabled via the Link
component exported by next/link
.
An example of linking to /
and /about
:
import Link from 'next/link'
function Home() {
return (
<ul>
<li>
<Link href="/">
<a>Home</a>
</Link>
</li>
<li>
<Link href="/about">
<a>About Us</a>
</Link>
</li>
</ul>
)
}
export default Home
Link
accepts the following props:
href
- The path insidepages
directory. This is the only required propas
- The path that will be rendered in the browser URL bar. Used for dynamic routespassHref
- ForcesLink
to send thehref
property to its child. Defaults tofalse
prefetch
- Prefetch the page in the background. Defaults totrue
replace
- Replace the currenthistory
state instead of adding a new url into the stack. Defaults tofalse
scroll
- Scroll to the top of the page after a navigation. Defaults totrue
Dynamic routes
A Link
to a dynamic route is a combination of the href
and as
props. A link to the page pages/post/[pid].js
will look like this:
<Link href="/post/[pid]" as="/post/abc">
<a>First Post</a>
</Link>
href
is a file system path used by the page and it shouldn't change at runtime. as
on the other hand, will be dynamic most of the time according to your needs. Here's an example of how to create a list of links:
const pids = ['id1', 'id2', 'id3']
{
pids.map(pid => (
<Link href="/post/[pid]" as={`/post/${pid}`}>
<a>Post {pid}</a>
</Link>
))
}
Example with React.forwardRef
If the child component in Link
is a function component, you'll need to wrap it in React.forwardRef
like in the following example:
import React from 'react'
import Link from 'next/link'
// `onClick`, `href`, and `ref` need to be passed to the DOM element
// for proper handling
const MyButton = React.forwardRef(({ onClick, href }, ref) => {
return (
<a href={href} onClick={onClick} ref={ref}>
Click Me
</a>
)
})
function Home() {
return (
<Link href="/about">
<MyButton />
</Link>
)
}
export default Home
With URL Object
Link
can also receive an URL object and it will automatically format it to create the URL string. Here's how to do it:
import Link from 'next/link'
function Home() {
return (
<div>
<Link href={{ pathname: '/about', query: { name: 'ZEIT' } }}>
<a>About us</a>
</Link>
</div>
)
}
export default Home
The above example will be a link to /about?name=ZEIT
. You can use every property as defined in the Node.js URL module documentation.
Replace the URL instead of push
The default behavior of the Link
component is to push
a new URL into the history
stack. You can use the replace
prop to prevent adding a new entry, as in the following example:
<Link href="/about" replace>
<a>About us</a>
</Link>
Using a component that supports onClick
Link
supports any component that supports the onClick
event, in the case you don't provide an <a>
tag, consider the following example:
<Link href="/about">
<img src="/static/image.png" alt="image" />
</Link>
The child of Link
is <img>
instead of <a>
. Link
will send the onClick
property to <img>
but won't pass the href
property.
Forcing Link
to expose href
to its child
If the child is an <a>
tag and doesn't have a href
attribute we specify it so that the repetition is not needed by the user. However, sometimes, you’ll want to pass an <a>
tag inside of a wrapper and Link
won’t recognize it as a hyperlink, and, consequently, won’t transfer its href
to the child.
In cases like that, you can add the passHref
property to Link
, forcing it to expose its href
property to the child. Take a look at the following example:
import Link from 'next/link'
import Unexpected_A from 'third-library'
function NavLink({ href, name }) {
return (
<Link href={href} passHref>
<Unexpected_A>{name}</Unexpected_A>
</Link>
)
}
export default NavLink
Please note: using a tag other than
<a>
and failing to passpassHref
may result in links that appear to navigate correctly, but, when being crawled by search engines, will not be recognized as links (owing to the lack ofhref
attribute). This may result in negative effects on your sites SEO.
Disable scrolling to the top of the page
The default behavior of Link
is to scroll to the top of the page. When there is a hash defined it will scroll to the specific id, just like a normal <a>
tag. To prevent scrolling to the top / hash scroll={false}
can be added to Link
:
<Link href="/?counter=10" scroll={false}>
<a>Disables scrolling to the top</a>
</Link>