Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Community Plugin
View plugin on GitHub

Banner

Gatsby Smooth Scroll Anchor Links

Why? What does this do?

Many sites use a mixed navigation format in which some links route to other pages, while some anchor a smooth scroll to sections within a specific page — but both types still need to function well regardless of what page the user is currently on. This can be a little cumbersome to accomplish elegantly. This plugin aims to provide that. You can read a little more about the evolution of the logic in the plugin on my web development blog.

This plugin adds a check onRouteUpdate - which looks for hashes in the current pathname. If so, it uses a scrolling library to scroll to the provided hash. In addition, it provides component(s) for use in your Gatsby code to which you can provide both hashed & non-hashed to paths.

Installation

Using Yarn

  • yarn add gatsby-plugin-anchor-links

Using NPM

  • npm i gatsby-plugin-anchor-links

gatsby-config.js

This plugin can be used with or without a configuration object:

module.exports = {
  plugins: [`gatsby-plugin-anchor-links`]
};
module.exports = {
  plugins: [
    {
      resolve: "gatsby-plugin-anchor-links",
      options: {
        offset: -100
      }
    }
  ]
};

Configuration Options

Option Description Default Type
offset # of pixels from top 0 number
duration duration of scroll in milliseconds 1000 number

Component usage

You can provide anchor or non-anchor links to this component for ease of use. If you use it as an anchor component, be sure to include both a base path and hash in the to string.

import { AnchorLink } from "gatsby-plugin-anchor-links";

export default () => (
  <AnchorLink to="/about#team" title="Our team">
    <span>Check out our team!</span>
  </AnchorLink>
);
// => <a href="/about#team" title="Our team"><span>Check out our team!</span></a>

export default () => (
  <AnchorLink to="/about#team" title="Check out our team!" />
);
// => <a href="/about#team" title="Check out our team!">Check out our team!</a>

export default () => (
  <AnchorLink
    to="/about#team"
    title="Check out our team!"
    className="stripped"
    stripHash
  />
);
// => <a href="/about" class="stripped" title="Check out our team!">Check out our team!</a>
// => Hash will be stripped, and a full page scroll will occure onRouteChange

export default () => <AnchorLink to="/about" title="About us" />;
// => <a href="/about" title="About us">About us</a>
Option Description Type Required
to path with hash to your page & anchor string true
title accessible title & fallback anchor text string false
className className to be passed to gatsby-link component string false
stripHash strips hash from link - forces a full scroll to target onRouteChange boolean false
gatsbyLinkProps a passthrough object which is spread into Link props object false
onAnchorLinkClick a function to be called when the anchor link handler is fired function false
children react node to be wrapped by AnchorLink react node false

A note on stripHash

When passing a hashed to prop to the link component - browsers will automatically try to get you there when the route changes. If you have some offset value, you’ll see some scrolling action. If you don’t, you’ll just see a static route change directly to the hash.

The stripHash prop will route to the base path of your to prop, save the hash on the window, then navigate to it. As far as semantic HTML & Google SERP nav links concerned, this probably isn’t exactly 100% kosher in every sitation, but it achieves the desired effect for many that are looking for this kind of solution. So, take this with a grain of salt.

Credits

© 2024 Gatsby, Inc.