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
Credits
- Anchor logo by dData via Noun Project