Gatsby Link Component and Navigation — Client-Side Routing

In this tutorial, you will learn about Gatsby Link Component and Navigation. We cover key concepts, practical examples, and best practices to help you master this topic.

Learn Gatsby's Link component for client-side navigation, prefetching, active link styling, and navigation patterns for fast React static sites.

In this lesson, you'll understand how Link enables client-side routing, how prefetching works, and how to style active links.

What You'll Learn

How to use Link for internal navigation, how Gatsby prefetches pages, how to style active and partially active links, and navigation patterns.

Why It Matters

Client-side navigation provides instant page transitions without full reloads. Gatsby's prefetching makes navigation feel instant by loading linked pages in the background.

flowchart LR
    A[User Hovers Link] --> B[Prefetch Triggered]
    B --> C[Page JS + Data Loaded]
    C --> D[User Clicks Link]
    D --> E[Instant Render]
    style B fill:#639,color:#fff
    style E fill:#4a148c,color:#fff

Basic Link Usage

import { Link } from 'gatsby';
import React from 'react';

function Nav() {
  return (
    <nav>
      <Link to="/">Home</Link>
      <Link to="/about/">About</Link>
      <Link to="/blog/">Blog</Link>
      <Link to="/contact/">Contact</Link>
    </nav>
  );
}

Output: Clicking a Link navigates to the new page without a full browser reload. Gatsby automatically prefetches the linked page's data in the background.

Active Link Styling

Add styles for the currently active page:

import { Link } from 'gatsby';
import React from 'react';

function Nav() {
  return (
    <nav>
      <Link to="/" activeStyle={{ fontWeight: 'bold', color: '#639' }}>
        Home
      </Link>
      <Link to="/about/" activeClassName="active-link">
        About
      </Link>
      <Link to="/blog/" partiallyActive activeClassName="active-parent">
        Blog
      </Link>
    </nav>
  );
}

Output: The Home link uses activeStyle for inline styles. About uses activeClassName for CSS classes. Blog uses partiallyActive to highlight when on any /blog/ subpage.

Navigate Component

Programmatic navigation:

import { navigate } from 'gatsby';
import React from 'react';

function LoginButton() {
  const handleLogin = async () => {
    await loginUser();
    navigate('/dashboard/', { replace: true });
  };

  return <button onClick={handleLogin}>Login</button>;
}

The navigate function programmatically navigates to a new URL. The replace option replaces the current history entry instead of pushing a new one.

Link with State

Pass state through navigation:

import { Link } from 'gatsby';
import React from 'react';

function ProductCard({ product }) {
  return (
    <Link
      to={`/products/${product.slug}/`}
      state={{ fromList: true, category: product.category }}
    >
      <h3>{product.name}</h3>
    </Link>
  );
}

// In the target page:
function ProductPage({ location }) {
  const cameFromList = location.state?.fromList;
  return <div>{cameFromList && <Link to="/products/">Back to list</Link>}</div>;
}

Output: State passes through navigation without appearing in the URL. The target page reads location.state to show or hide a "Back" link.

Common Mistakes

1. Using <a> for internal links: Regular anchor tags cause full page reloads, losing application state and prefetching benefits.
2. Forgetting trailing slashes: Gatsby expects trailing slashes in to paths. Use /about/ not /about.
3. Not using partiallyActive for parent nav items: Without it, the parent link in a dropdown nav won't highlight when on a child page.
4. Using activeStyle with CSS-in-JS: activeStyle accepts a style object. For theme-aware styles, use activeClassName with styled-components or emotion.
5. Passing objects in state that aren't serializable: State must be serializable. Avoid passing functions or circular references.

Practice Questions

1. What does Gatsby prefetch do? Answer: It loads the JavaScript and data for linked pages in the background when the user hovers over a Link, making navigation instant.

2. How do you style the currently active link? Answer: Use activeStyle for inline styles or activeClassName for a CSS class. Add partiallyActive for parent links.

3. What is the difference between navigate and Link? Answer: Link is a component for declarative navigation in JSX. navigate is a function for programmatic navigation in event handlers or effects.

4. How do you pass data through navigation without visible URL parameters? Answer: Use the state prop on Link or the second argument of navigate. Access it via location.state in the target page.

Challenge

Build a navigation bar with dropdown menus. Each dropdown parent should highlight when any child page is active. Use partiallyActive and include breadcrumb-style navigation on subpages.

Mini Project

Create a documentation site layout with sidebar navigation. Use activeClassName and partiallyActive for the sidebar links. Include a breadcrumb trail at the top of each page.

FAQ

What's Next

Learn about Gatsby Config and Plugins to configure your site and extend functionality with Gatsby's plugin ecosystem.