ryan-teliczan / gatsby-plugin-anchor-links

⚓ Gatsby plugin for using smooth scroll anchor links with a Gatsby Link component

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

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>

AnchorLink props

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

Sites using Gatsby Anchor Links

• chaseohlson.com // source

Credits

• Anchor logo by dData via Noun Project