Gatsby: The Definitive Guide

Appendix B. Gatsby Component APIs

This appendix provides a comprehensive account of the APIs for Gatsby’s built-in <Link /> and image components.

<Link />

The Gatsby <Link /> component is used in Gatsby applications to power linking between internal pages generated by Gatsby and to enable preloading of resources on other pages such that when the link is clicked, the change is instantaneous.

Warning

The Gatsby <Link /> component should be used only for internal (not external) links. For more information about how to handle situations in which a link’s internal or external target is uncertain, consult the Gatsby documentation’s guide to relative links.

When the <Link /> component is visible within the browser viewport, Gatsby uses an IntersectionObserver to perform a low-priority fetch. When an onMouseOver event on the <Link /> component occurs, this triggers a high-priority fetch as it is likely the user is about to navigate to that resource.

At its core, the <Link /> component is a wrapper around the Link component provided by @reach/router with Gatsby-specific enhancements, and all props provided are also passed to @reach/router’s Link component.

Note

Gatsby uses the withPrefix helper function to construct pathnames that respect configured path prefixes in uses of the <Link /> component or the navigate function (see “navigate”).

<Link /> Usage

You should use the <Link /> component as a replacement for HTML <a> tags that represent links between pages in the same Gatsby site. ...