Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ContactSign Up
Official Plugin
View plugin on GitHub


This plugin intercepts all local links that have not been created in React using gatsby-link, and replaces their behavior with that of the gatsby-link navigate. This avoids the browser having to refresh the whole page when navigating between local pages, preserving the Single Page Application (SPA) feel.

Example use cases:

  • A markdown file with relative links (transformed to a tags by gatsby-transformer-remark)
  • An a tag that has been created by a Content Management System (CMS) WYSIWYG editor


npm install gatsby-plugin-catch-links

How to use

// In your gatsby-config.js
plugins: [`gatsby-plugin-catch-links`]

Plugin Options

excludePattern [Regular Expression][optional]

Regular expression for paths to be excluded from being handled by this plugin.

  resolve: `gatsby-plugin-catch-links`,
  options: {
    excludePattern: /(excluded-link|external)/,


  • Check out this live example Using Remark to see this plugin in action. The full source code for this example can be found here.
© 2023 Gatsby, Inc.