<Link>

<Link> is used to navigate between pages

An example of linking to Home and About:

import {Link, Routes} from "blitz"

function Home() {
  return (
    <ul>
      <li>
        <Link href={Routes.Home()}> // Option 1: use Route manifest
        <Link href="/"> // Option 2: use string or location object
          <a>Home</a>
        </Link>
      </li>
      <li>
        <Link href={Routes.About()}> // Option 1: use Route manifest
        <Link href="/about"> // Option 2: use string or location object
          <a>About Us</a>
        </Link>
      </li>
    </ul>
  )
}

export default Home

The Routes object imported from blitz is automatically generated based on the pages in your app. If your page component is named About, then you can link to it with Routes.About. For more information, see the Route Manifest documentation.

Link accepts the following props:

href - The path inside pages directory. This is the only required prop.
as - The path that will be rendered in the browser URL bar. Used for dynamic routes
passHref - Forces Link to send the href property to its child. Defaults to false
prefetch - Prefetch the page in the background. Defaults to true. Any <Link /> that is in the viewport (initially or through scroll) will be preloaded. Prefetch can be disabled by passing prefetch={false}. When prefetch is set to false, prefetching will still occur on hover. Pages using Static Generation will preload JSON files with the data for faster page transitions. Prefetching is only enabled in production.
replace - Replace the current history state instead of adding a new url into the stack. Defaults to false
scroll - Scroll to the top of the page after a navigation. Defaults to true
shallow - Update the path of the current page without rerunning getStaticProps or getServerSideProps. Defaults to false

External URLs, and any links that don't require a route navigation using /pages, don't need to be handled with Link; use the anchor tag for such cases instead.

Dynamic routes

A Link to a dynamic route works like the other links. A link to the page pages/post/[pid].js will look like this:

<Link href={Routes.Post({ pid: "abc" })}>
  <a>First Post</a>
</Link>

Here's an example of how to create a list of links:

const pids = ["id1", "id2", "id3"]
{
  pids.map((pid) => (
    <Link href={Routes.Post({pid})}> // using Routes Manifest
    <Link href={`/posts/${pid}`}> // using location
      <a>Post {pid}</a>
    </Link>
  ))
}

If the child is a custom component that wraps an `<a>` tag

If the child of Link is a custom component that wraps an <a> tag, you must add passHref to Link. This is necessary if you’re using libraries like styled-components. Without this, the <a> tag will not have the href attribute, which might hurt your site’s SEO.

import { Link } from "blitz"
import styled from "styled-components"

// This creates a custom component that wraps an <a> tag
const RedLink = styled.a`
  color: red;
`

function NavLink({ href, name }) {
  // Must add passHref to Link
  return (
    <Link href={href} passHref>
      <RedLink>{name}</RedLink>
    </Link>
  )
}

export default NavLink

Note: If you’re using emotion’s JSX pragma feature (@jsx jsx), you must use passHref even if you use an <a> tag directly.

If the child is a function component

If the child of Link is a function component, in addition to using passHref, you must wrap the component in React.forwardRef:

import { Link, Routes } from "blitz"

// `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={Routes.About()} passHref>
      <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 "blitz"

function Home() {
  return (
    <div>
      <Link href={{ pathname: "/about", query: { name: "test" } }}>
        <a>About us</a>
      </Link>
    </div>
  )
}

export default Home

The above example will be a link to /about?name=test. 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={Routes.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={Routes.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.

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, 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>

Topics